El punto de conexión de redireccionamiento y autorización - Amazon Cognito
GET /oauth2/authorizeEjemplo: concesión de un código de autorizaciónEjemplo: concesión de código de autorización con PKCEEjemplo: requerir una nueva autenticación con prompt=loginEjemplo: autenticación silenciosa con prompt=noneEjemplo: concesión simbólica (implícita) sin ámbito openidEjemplo: concesión simbólica (implícita) con alcance openidRespuestas de error

Las traducciones son generadas a través de traducción automática. En caso de conflicto entre la traducción y la version original de inglés, prevalecerá la version en inglés.

El punto de conexión de redireccionamiento y autorización

El punto de conexión /oauth2/authorize es un punto de conexión de redirección que admite dos destinos de redireccionamiento. Si incluye un parámetro identity_provider o idp_identifier en la URL, redirige al usuario de forma silenciosa a la página de inicio de sesión de ese proveedor de identidades (IdP). De lo contrario, redirige al Punto de conexión Login con los mismos parámetros de URL incluidos en la solicitud.

El punto final de autorización redirige al inicio de sesión administrado o a una página de inicio de sesión del IdP. El destino de una sesión de usuario en este punto de conexión es una página web con la que su usuario debe interactuar directamente en su navegador.

Para usar el punto de conexión de autorización, invoque el navegador de su usuario en /oauth2/authorize con parámetros que proporcionan a su grupo de usuarios información sobre los siguientes detalles del grupo de usuarios.

  • El cliente de aplicación en el que desea iniciar sesión.

  • La URL de devolución de llamada en la que quiere terminar.

  • Los ámbitos OAuth 2.0 que quieres solicitar en el token de acceso de tu usuario.

  • De manera opcional, el IdP de terceros que desea usar para iniciar sesión.

También puede suministrar los parámetros state y nonce que Amazon Cognito utiliza para validar las notificaciones entrantes.

GET /oauth2/authorize

El punto de enlace /oauth2/authorize solo admite HTTPS GET. Por lo general, la aplicación inicia esta solicitud en el navegador del usuario. Solo puede hacer solicitudes a los puntos de conexión de /oauth2/authorize sobre HTTPS.

Puede obtener más información sobre la definición del punto de conexión de autorización en el estándar OpenID Connect (OIDC) en Punto de conexión de autorización.

Parámetros de solicitud

response_type

Obligatorio.

El tipo de respuesta. Debe ser code o token.

Una solicitud exitosa con un response_type de code devuelve una concesión de código de autorización. Una concesión de código de autorización es un parámetro code que Amazon Cognito añade a la URL de redireccionamiento. Su aplicación puede intercambiar el código con el Punto de conexión de token para tokens de acceso, ID y actualización. Como práctica recomendada de seguridad, y para recibir tokens de actualización para sus usuarios, use un código de autorización de concesión en su aplicación.

Una solicitud exitosa con un response_type de token devuelve una concesión de código de autorización. Una concesión implícita es un identificador y un token de acceso que Amazon Cognito añade a la URL de redireccionamiento. Una concesión implícita es menos segura porque expone los tokens y la posible información de identificación a los usuarios. Puede desactivar la compatibilidad con las concesiones implícitas en la configuración del cliente de su aplicación.

client_id

Obligatorio.

El ID de cliente de aplicación.

El valor de client_id debe ser el ID de un cliente de aplicación del grupo de usuarios en el que se realiza la solicitud. El cliente de la aplicación debe admitir el inicio de sesión de los usuarios locales de Amazon Cognito o de al menos un IdP de terceros.

redirect_uri

Obligatorio.

La dirección URL a la que el servidor de autenticación redirige el navegador después de que Amazon Cognito autorice al usuario.

Un identificador uniforme de recursos (URI) de redirección debe tener los siguientes atributos:

  • Ser un URI absoluta

  • Debe haber registrado el URI previamente en un cliente.

  • No puede incluir un componente fragmento.

Consulte OAuth 2.0: Punto final de redirección.

Amazon Cognito requiere que el URI de redireccionamiento use HTTPS, excepto para http://localhost, que puede configurar como URL de devolución de llamada para pruebas.

Amazon Cognito también admite la devolución de llamadas a aplicaciones, como. URLs myapp://example

state

Opcional, recomendado.

Cuando su aplicación agrega un parámetro state a una solicitud, Amazon Cognito devuelve su valor a la aplicación cuando el punto de conexión /oauth2/authorize redirige al usuario.

Agregue este valor a sus solicitudes de protección contra ataques CSRF.

No se puede establecer el valor de un parámetro state a una cadena JSON codificada en URL. Para pasar una cadena que coincida con este formato en un parámetro state, codifique la cadena en base64 y luego descodifíquela en la aplicación.

identity_provider

Opcional.

Agregue este parámetro para omitir el inicio de sesión administrado y redirigir al usuario a la página de inicio de sesión de un proveedor. El valor delidentity_provideres el nombre del proveedor de identidad (IdP) tal como aparece en el grupo de usuarios.

  • En el caso de los proveedores de redes sociales, puede usar los valores de identity_provider Facebook, Google, LoginWithAmazon y SignInWithApple.

  • En cuanto a los grupos de usuarios de Amazon Cognito, utilice el valor COGNITO.

  • Para los proveedores de identidad SAML 2.0 y OpenID Connect (OIDC) (IdPs), usa el nombre que asignaste al IdP en tu grupo de usuarios.

idp_identifier

Opcional.

Agregue este parámetro para redirigir a un proveedor con un nombre alternativo para el nombre identity_provider. Puede introducir los identificadores de SAML 2.0 y OIDC en el menú IdPs de proveedores sociales y externos de la consola de Amazon Cognito.

scope

Opcional.

Puede ser una combinación de cualquier ámbito reservado por el sistema o ámbitos personalizados asociados a un cliente. Los ámbitos deben estar separados por espacios. Los ámbitos reservados por el sistema son openid, email, phone, profile y aws.cognito.signin.user.admin. Todo ámbito utilizado debe estar asociado al cliente o se ignorará en el tiempo de ejecución.

Si el cliente no solicita ningún ámbito, en el servidor de autenticación se utilizarán todos los ámbitos asociados al cliente.

Solo se devuelve un token de ID si se solicita el ámbito openid. El token de acceso solo se puede utilizar en grupos de usuarios de Amazon Cognito si se solicita el ámbito aws.cognito.signin.user.admin. Los ámbitos phone, email y profile solo se pueden solicitar si se solicita también el ámbito openid. Estos ámbitos dictan las notificaciones que se incluyen en el token de ID.

code_challenge_method

Opcional.

El protocolo de hash que utilizó para generar el desafío. En el PKCE RFC, se definen dos métodos, S256 y sin formato; sin embargo, el servidor de autenticación de Amazon Cognito solo admite S256.

code_challenge

Opcional.

El desafío de prueba de intercambio de códigos clave (PKCE) que generaste a partir del. code_verifier Para obtener más información, consulte Uso de la PKCE en las concesiones de códigos de autorización.

Obligatorio solo cuando se especifica un parámetro code_challenge_method.

nonce

Opcional.

Valor aleatorio que puede agregar a la solicitud. El valor nonce que proporciona se incluye en el token de ID que emite Amazon Cognito. Para protegerse de los ataques de reproducción, su aplicación puede inspeccionar la reclamación de nonce en el token de identificación y compararlo con el generado. Para obtener más información sobre la reclamación de nonce, consulte ID token validation (Validación de token de ID) en el estándar de OpenID Connect.

lang

Opcional.

El idioma en el que desea mostrar las páginas interactivas para el usuario. Las páginas de inicio de sesión gestionadas se pueden localizar, pero las páginas de la interfaz de usuario alojada (clásicas) no. Para obtener más información, consulte Localización de inicios de sesión gestionados.

login_hint

Opcional.

La petición de nombre de usuario que desea pasar al servidor de autorización. Puede recopilar el nombre de usuario, la dirección de correo electrónico o el número de teléfono del usuario y permitir que el proveedor de destino rellene previamente el nombre de inicio de sesión del usuario. Al enviar un login_hint parámetro y ningún idp_identifier identity_provider parámetro al oauth2/authorize punto final, el inicio de sesión gestionado rellena el campo del nombre de usuario con el valor de sugerencia. También puede pasar este parámetro al Punto de conexión Login y rellenar automáticamente el valor del nombre de usuario.

Cuando su solicitud de autorización invoca una redirección a OIDC IdPs o Google, Amazon Cognito añade un login_hint parámetro a la solicitud a ese autorizador externo. No puedes reenviar las sugerencias de inicio de sesión a SAML, Apple, Login With Amazon o Facebook (Meta) IdPs.

prompt

Opcional.

Parámetro del OIDC que controla el comportamiento de autenticación de las sesiones existentes. Disponible solo en la versión de marca de inicio de sesión gestionado, no en la interfaz de usuario alojada clásica. Para obtener más información sobre la especificación OIDC, consulte Solicitud de autenticación. Los valores none y login tienen un efecto en el comportamiento de autenticación del grupo de usuarios.

Amazon Cognito reenvía todos los valores prompt excepto none a usted IdPs cuando los usuarios seleccionan la autenticación con proveedores externos. Esto ocurre cuando la URL a la que acceden los usuarios incluye un idp_identifier parámetro identity_provider o, o cuando el servidor de autorización los redirige a Punto de conexión Login y ellos seleccionan un IdP entre los botones disponibles.

Indique los valores de los parámetros
prompt=none

Amazon Cognito continúa la autenticación de forma silenciosa para los usuarios que tienen una sesión autenticada válida. Con este mensaje, los usuarios pueden autenticarse de forma silenciosa entre diferentes clientes de aplicaciones de su grupo de usuarios. Si el usuario aún no se ha autenticado, el servidor de autorización devuelve un error. login_required

prompt=login

Amazon Cognito requiere que los usuarios se vuelvan a autenticar aunque tengan una sesión existente. Envíe este valor cuando desee volver a verificar la identidad del usuario. Los usuarios autenticados que tienen una sesión existente pueden volver a iniciar sesión sin invalidar esa sesión. Cuando un usuario que tiene una sesión existente vuelve a iniciar sesión, Amazon Cognito le asigna una nueva cookie de sesión. Este parámetro también se puede reenviar a su dirección. IdPs IdPslos que aceptan este parámetro también solicitan al usuario un nuevo intento de autenticación.

prompt=select_account

Este valor no afecta al inicio de sesión local y debe enviarse en las solicitudes que redirijan a IdPs. Cuando se incluye en la solicitud de autorización, este parámetro se añade prompt=select_account a la ruta URL del destino de redireccionamiento del IdP. Cuando IdPs admiten este parámetro, solicitan a los usuarios que seleccionen la cuenta con la que desean iniciar sesión.

prompt=consent

Este valor no afecta al inicio de sesión local y debe enviarse en las solicitudes que redirijan a IdPs. Cuando se incluye en la solicitud de autorización, este parámetro se añade prompt=consent a la ruta URL del destino de redireccionamiento del IdP. Cuando IdPs admiten este parámetro, solicitan el consentimiento del usuario antes de volver a redirigirlo a su grupo de usuarios.

Al omitir el prompt parámetro de la solicitud, el inicio de sesión administrado sigue el comportamiento predeterminado: los usuarios deben iniciar sesión a menos que su navegador tenga una cookie de sesión de inicio de sesión administrada válida. Puede combinar varios valores prompt con un delimitador de caracteres y espacios, por ejemplo. prompt=login consent

Ejemplo: concesión de un código de autorización

A continuación mostramos un ejemplo de solicitud de concesión de código de autorización.

La solicitud siguiente inicia una sesión para recuperar un código de autorización que el usuario pasa a la aplicación en el destino de redirect_uri. En dicha sesión, se solicitan los ámbitos de los atributos de usuario y el acceso a las operaciones de la API de autoservicio de Amazon Cognito.

GET https://mydomain.auth.us-east-1.amazoncognito.com/oauth2/authorize?
response_type=code&
client_id=1example23456789&
redirect_uri=https://www.example.com&
state=abcdefg&
scope=openid+profile+aws.cognito.signin.user.admin

El servidor de autenticación de Amazon Cognito redirige a la aplicación con el código y el estado de autorización. El código de autorización es válido durante cinco minutos.

HTTP/1.1 302 Found
Location: https://www.example.com?code=a1b2c3d4-5678-90ab-cdef-EXAMPLE11111&state=abcdefg

Ejemplo: concesión de código de autorización con PKCE

Este flujo de ejemplo realiza una concesión de código de autorización con PKCE.

Esta solicitud agrega un code_challenge parámetro. Para intercambiar un código por un token, debe incluir el parámetro code_verifier en la solicitud para el punto de conexión /oauth2/token.

GET https://mydomain.auth.us-east-1.amazoncognito.com/oauth2/authorize?
response_type=code&
client_id=1example23456789&
redirect_uri=https://www.example.com&
state=abcdefg&
scope=aws.cognito.signin.user.admin&
code_challenge_method=S256&
code_challenge=a1b2c3d4...

El servidor de autorización redirige de nuevo a su aplicación con el código y el estado de autorización. La aplicación procesa el código de autorización y lo cambia por fichas.

HTTP/1.1 302 Found
Location: https://www.example.com?code=a1b2c3d4-5678-90ab-cdef-EXAMPLE11111&state=abcdefg

Ejemplo: requerir una nueva autenticación con prompt=login

La siguiente solicitud agrega un prompt=login parámetro que requiere que el usuario se autentique nuevamente, incluso si ya tiene una sesión existente.

GET https://mydomain.auth.us-east-1.amazoncognito.com/oauth2/authorize?
response_type=code&
client_id=1example23456789&
redirect_uri=https://www.example.com&
state=abcdefg&
scope=openid+profile+aws.cognito.signin.user.admin&
prompt=login

El servidor de autorización redirige al punto final de inicio de sesión, por lo que es necesario volver a autenticarse.

HTTP/1.1 302 Found Location: https://mydomain.auth.us-east-1.amazoncognito.com/login?response_type=code&client_id=1example23456789&redirect_uri=https://www.example.com&state=abcdefg&scope=openid+profile+aws.cognito.signin.user.admin&prompt=login

Ejemplo: autenticación silenciosa con prompt=none

La siguiente solicitud agrega un prompt=none parámetro que comprueba silenciosamente si el usuario tiene una sesión válida.

GET https://mydomain.auth.us-east-1.amazoncognito.com/oauth2/authorize?
response_type=code&
client_id=1example23456789&
redirect_uri=https://www.example.com&
state=abcdefg&
scope=openid+profile+aws.cognito.signin.user.admin&
prompt=none

Cuando no existe una sesión válida, el servidor de autorización devuelve un error al URI de redireccionamiento

HTTP/1.1 302 Found Location: https://www.example.com?error=login_required&state=abcdefg

Cuando existe una sesión válida, el servidor de autorización devuelve un código de autorización.

HTTP/1.1 302 Found Location: https://www.example.com?code=AUTHORIZATION_CODE&state=abcdefg

Ejemplo: concesión simbólica (implícita) sin ámbito openid

Este flujo de ejemplo genera una concesión implícita y regresa JWTs directamente a la sesión del usuario.

La solicitud es para una concesión implícita de su servidor de autorización. Solicita ámbitos en el token de acceso que autoricen las operaciones de autoservicio del perfil de usuario.

GET https://mydomain.auth.us-east-1.amazoncognito.com/oauth2/authorize?
response_type=token&
client_id=1example23456789&
redirect_uri=https://www.example.com&
state=abcdefg&
scope=aws.cognito.signin.user.admin

El servidor de autorización redirige de nuevo a su aplicación únicamente con un token de acceso. Dado que no se ha solicitado el ámbito openid, Amazon Cognito no devuelve un token de ID. Además, Amazon Cognito no devuelve un token de actualización en este flujo.

HTTP/1.1 302 Found
Location: https://example.com/callback#access_token=eyJra456defEXAMPLE&token_type=bearer&expires_in=3600&state=STATE

Ejemplo: concesión simbólica (implícita) con alcance openid

Este flujo de ejemplo genera una concesión implícita y devuelve los tokens al navegador del usuario.

La solicitud es para una concesión implícita de su servidor de autorización. Solicita ámbitos en el token de acceso que autoricen el acceso a los atributos del usuario y a las operaciones de autoservicio.

GET
https://mydomain.auth.us-east-1.amazoncognito.com/oauth2/authorize? 
response_type=token& 
client_id=1example23456789& 
redirect_uri=https://www.example.com& 
state=abcdefg&
scope=aws.cognito.signin.user.admin+openid+profile

El servidor de autorización redirige de nuevo a tu aplicación con el token de acceso y el token de ID (porque el openid alcance estaba incluido):

HTTP/1.1 302 Found
Location: https://www.example.com#id_token=eyJra67890EXAMPLE&access_token=eyJra12345EXAMPLE&token_type=bearer&expires_in=3600&state=abcdefg

Ejemplos de respuestas negativas

Amazon Cognito podría denegar la solicitud. Las solicitudes negativas vienen con un código de error HTTP y una descripción que puede utilizar para corregir los parámetros de la solicitud. A continuación se proporcionan ejemplos de respuestas negativas.

  • Si client_id y redirect_uri son válidos, pero los parámetros de solicitud no tienen el formato correcto, el servidor de autenticación redirige el error al redirect_uri del cliente y añade un mensaje de error en un parámetro URL. A continuación se proporcionan ejemplos de formatos incorrectos.

    • La solicitud no incluye un parámetro response_type.

    • La solicitud de autorización ha proporcionado un parámetro code_challenge, pero no un parámetro code_challenge_method.

    • El valor del parámetro code_challenge_method no es S256.

    A continuación mostramos un ejemplo de respuesta con formato incorrecto.

    HTTP 1.1 302 Found Location: https://client_redirect_uri?error=invalid_request

  • Si el cliente solicita code o token en response_type, pero no tiene permiso para estas solicitudes, el servidor de autorización de Amazon Cognito devuelve unauthorized_client al redirect_uri del cliente, tal y como se indica a continuación:

    HTTP 1.1 302 Found Location: https://client_redirect_uri?error=unauthorized_client

  • Si el cliente solicita un ámbito no válido, desconocido o con un formato incorrecto, el servidor de autorización de Amazon Cognito devuelve invalid_scope al redirect_uri del cliente, tal y como se indica a continuación: 

    HTTP 1.1 302 Found Location: https://client_redirect_uri?error=invalid_scope

  • Si se produce algún error inesperado en el servidor, el servidor de autenticación devuelve server_error al redirect_uri del cliente. No debe mostrarse el error HTTP 500 en el navegador del usuario porque este error no se envía al cliente. El servidor de autorización devuelve el siguiente error.

    HTTP 1.1 302 Found Location: https://client_redirect_uri?error=server_error

  • Cuando Amazon Cognito se autentica mediante la federación con un tercero, Amazon IdPs Cognito puede experimentar problemas de conexión, como los siguientes:

    • Si se produce un tiempo de espera de conexión al solicitar un token desde el IdP, el servidor de autenticación redirecciona el error al redirect_uri del cliente como se muestra a continuación:

      HTTP 1.1 302 Found Location: https://client_redirect_uri?error=invalid_request&error_description=Timeout+occurred+in+calling+IdP+token+endpoint

    • Si se agota el tiempo de espera durante la llamada al punto de conexión jwks_uri para validar el token de ID, el servidor de autenticación redirige el error al redirect_uri del cliente, tal y como se indica a continuación:

      HTTP 1.1 302 Found Location: https://client_redirect_uri?error=invalid_request&error_description=error_description=Timeout+in+calling+jwks+uri

  • Al autenticarse mediante la federación con un tercero, es posible que los proveedores IdPs devuelvan respuestas de error. Esto puede deberse a errores de configuración u otros motivos, como los siguientes:

    • Si se recibe una respuesta de error de otros proveedores, el servidor de autenticación redirige el error al redirect_uri del cliente como se muestra a continuación:

      HTTP 1.1 302 Found Location: https://client_redirect_uri?error=invalid_request&error_description=[IdP name]+Error+-+[status code]+error getting token

    • Si se recibe una respuesta de error de Google, el servidor de autenticación redirige el error al redirect_uri del cliente como se muestra a continuación: 

      HTTP 1.1 302 Found Location: https://client_redirect_uri?error=invalid_request&error_description=Google+Error+-+[status code]+[Google-provided error code]

  • En caso de que Amazon Cognito encuentre una excepción de comunicación al realizar cualquier conexión con un IdP externo, el servidor de autenticación redirige con un error al redirect_uri del cliente con alguno de los siguientes mensajes:

    • HTTP 1.1 302 Found Location: https://client_redirect_uri?error=invalid_request&error_description=Connection+reset
    • HTTP 1.1 302 Found Location: https://client_redirect_uri?error=invalid_request&error_description=Read+timed+out