Pantalla de consentimiento
Qué ve la persona cuando tu aplicación pide acceso, cómo se agrupan los permisos, qué puede desactivar y cómo afecta eso al token que recibes.
Actualizado el . 6 min de lectura
La pantalla de consentimiento es donde la persona decide qué concede a tu aplicación. UTILIA OS le muestra quién pide acceso, con qué cuenta va a autorizar y qué podrá hacer la aplicación, en lenguaje claro y agrupado, y le deja desactivar lo que no quiera dar. Conocerla te ayuda a pedir lo justo y a entender por qué un token puede llegar con menos scopes de los que pediste.
Cuándo aparece
GET /api/oauth/authorizevalida la solicitud, la guarda durante 10 minutos y lleva a la persona a la pantalla (https://os.utilia.ai/oauth/authorize?request_id=...).- Si la persona no ha iniciado sesión, primero pasa por el inicio de sesión y después vuelve sola a la pantalla.
- Si tarda más de 10 minutos, la solicitud caduca y tiene que empezar de nuevo desde tu aplicación.
- Las aplicaciones marcadas como propias de UTILIA OS se saltan la pantalla cuando la persona ya tiene sesión, salvo que la solicitud lleve
prompt=consent. Esa marca solo la asigna UTILIA OS, así que una aplicación de terceros pasa siempre por la pantalla.
Qué ve la persona
La pantalla es una tarjeta con cinco zonas. En el ejemplo, una aplicación conecta el servidor MCP de CRM; en lugar de «tu aplicación», la persona ve el nombre con el que la registraste.
- Tu logotipo (el logo_uri del registro, o tu inicial si no hay) junto al de UTILIA OS, y la frase «Tu aplicación solicita acceso al MCP de CRM».
- «Conectado como», con la foto, el nombre y el correo de la persona. Con varias cuentas guardadas puede pulsar Cambiar; si no, Usar otra cuenta.
- Los permisos agrupados, cada uno con su interruptor activado. Los de identidad llevan «Siempre incluido»; los de borrar o acceso completo, «Alto impacto».
- Autorizar CRM: emite el código con lo que ha quedado activado y vuelve a tu redirect_uri.
- No permitir: vuelve a tu redirect_uri con error=access_denied.
Debajo de los botones están tus «Términos de servicio» y tu «Política de privacidad», si los configuraste, y la nota «Puedes revocar este acceso en cualquier momento desde la configuración de tu cuenta». Si un scope no encaja en ningún grupo, aparece en «Otros permisos que también se conceden» con su descripción: nada se concede sin enseñarse.
La marca «Verificada por UTILIA» solo la asigna la organización que administra UTILIA OS; si otra organización intenta activarla por la API, recibe un 403 con SAAS_ADMIN_REQUIRED_FOR_OAUTH_TRUST.
Cómo se recortan los permisos
Antes de pintar nada, la pantalla pregunta al servidor qué puede conceder esa persona (GET /api/oauth/user/scopes) y muestra solo la intersección con lo que pediste. Un scope desaparece si:
- La persona no tiene el permiso de UTILIA OS que le corresponde.
- Su organización no tiene contratado el aplicativo o la capacidad de ese scope.
- No pertenece al servidor MCP del
resource.
Si no pediste scope, se muestra el conjunto por defecto: los scopes permitidos en el registro de tu cliente o, si no tiene, solo los de identidad.
Si no queda nada que conceder, la persona ve «Acceso no autorizado», con el aviso de que no tiene los permisos necesarios y debe pedirlos al administrador de su organización. El botón Volver te la devuelve con access_denied.
La persona puede conceder menos de lo que pides
Al desactivar un grupo se quitan todos sus scopes, incluidos los conjuntos que lo cubrirían: si desactiva «Invitar y revocar usuarios del portal del cliente», también sale crm:full. El servidor aplica estas reglas al recibir la decisión:
- Solo puede reducir. Nada que no estuviera en tu solicitud puede añadirse.
- La identidad se conserva:
openid,profileyemailsiguen aunque no se manden. - Lo que queda tiene que servir al servidor MCP del
resource. Si con la selección tu aplicación no podría usar ese servidor, el botón de autorizar se desactiva y la pantalla lo explica: «Con esta selección, tu aplicación no podría usar CRM. Activa al menos un permiso de CRM». Sin servidor MCP, basta con la identidad. - Tu solicitud original queda registrada tal cual, aunque la persona conceda menos.
Lee el scope de la respuesta del token
El token puede llevar menos scopes de los que pediste. Comprueba el campo scope de la respuesta de POST /api/oauth/token y desactiva en tu aplicación lo que dependa de un scope no concedido. Las renovaciones conservan ese conjunto reducido: para recuperar un scope, vuelve a pedir autorización.
Grupos de permisos
Los nombres de los grupos dependen del servidor MCP que se conecta, porque cada uno los escribe desde su punto de vista: el mismo scope puede llamarse distinto en dos servidores. Sin resource, se usa una lista neutra. Algunos ejemplos de la lista neutra:
| Grupo | Marca | Qué incluye, por ejemplo |
|---|---|---|
| Ver tu información básica | Siempre incluido | openid, profile |
| Ver tu correo electrónico | Siempre incluido | email |
| Ver datos del CRM | crm:clients:view, crm:leads:view, crm:read | |
| Crear y modificar datos del CRM | crm:clients:create, crm:leads:convert, crm:write | |
| Eliminar y fusionar datos del CRM | Alto impacto | crm:clients:delete, crm:clients:merge |
| Acceso completo al CRM | Alto impacto | crm:full |
No uses estos nombres como contrato: pueden cambiar para explicar mejor lo que se concede. Lo que manda es la lista de scopes del token.
Consejos para tu aplicación
- Configura el logotipo, para que la persona reconozca tu aplicación en la cabecera.
- Configura los términos de servicio y la política de privacidad: dan confianza. Se hace en Activar OAuth en tu aplicación.
- Pide lo mínimo. Usa scopes individuales en lugar de conjuntos amplios como
crm:fullsi solo necesitas una parte: cuanto menos pidas, menos grupos de «Alto impacto» verá la persona. - Indica
resourcesi vas a llamar a un servidor MCP: los permisos se presentan desde el punto de vista de ese servidor y la persona entiende mejor qué concede.
Endpoint de la solicitud pendiente
/api/oauth/authorize-request/:idDatos de una solicitud de autorización pendiente. Lo usa la propia pantalla.
La pantalla recupera con este endpoint los datos de la solicitud: tu client_id, el nombre y el logotipo de tu aplicación, los enlaces legales y los scopes. Es público porque se consulta antes de iniciar sesión, no contiene secretos y admite 60 peticiones por minuto. Si la solicitud ha caducado, responde 400. Tu aplicación no necesita llamarlo.
Después de la autorización, la persona ve tu aplicación en Perfil › Aplicaciones, con lo que puede hacer, y desde ahí puede retirarle el acceso en cualquier momento.