El punto de conexión de redireccionamiento y autorización - Amazon Cognito
GET /oauth2/authorizeEjemplo de solicitudes con respuestas positivasEjemplos de respuestas negativas

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 de conexión de autorización redirige a la interfaz de usuario alojada o a la página de inicio de sesión de 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 de OAuth 2.0 que desea solicitar en el token de acceso de su 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 del cliente de la 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 - Redirection Endpoint.

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 las URL de devolución de llamada de aplicación como myapp://example.

state

(Opcional, recomendado) Cuando la aplicación añade 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) Añada este parámetro para omitir la interfaz de usuario alojada y redirigir al usuario a la página de inicio de sesión del 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 identidades (IdP) de SAML 2.0 y OpenID Connect (OIDC), utilice el nombre asignado al IdP en el grupo de usuarios.

idp_identifier

(Opcional) Añada este parámetro para redirigir a un proveedor con un nombre alternativo para el nombre del identity_provider. Puede introducir identificadores para sus IdP SAML 2.0 y OIDC desde la pestaña Sign-in experience (Experiencia de inicio de sesión) de la consola de Amazon Cognito.

scope

(Opcional) Puede ser una combinación de cualquier ámbito reservado por el sistema o ámbito personalizado asociado 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 ha utilizado 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 ha generado a partir de 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 añadir 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.

login_hint

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. Cuando envía un parámetro login_hint y ningún parámetro idp_identifier o identity_provider al punto de conexión oauth2/authorize, la interfaz de usuario alojada rellena el campo del nombre de usuario con el valor de la 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 la solicitud de autorización invoca una redirección a los IdP OIDC o a Google, Amazon Cognito añade un parámetro login_hint a la solicitud para ese autorizador externo. No puede reenviar las sugerencias de inicio de sesión a los IdP SAML, Apple, Login With Amazon o Facebook (Meta).

Ejemplo de solicitudes con respuestas positivas

En los siguientes ejemplos se ilustra el formato de las solicitudes HTTP realizadas al punto de conexión /oauth2/authorize.

Concesión de código de autorización

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

Ejemplo: Solicitud GET

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
Ejemplo: Respuesta

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

Concesión de código de autorización con PKCE

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

Ejemplo: Solicitud GET

La siguiente solicitud añade un parámetro code_challenge a la solicitud anterior. 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...
Ejemplo: Respuesta

El servidor de autenticación devuelve la redirección a la aplicación con el estado y el código de autorización. El código y el estado deben devolverse en los parámetros de la cadena de consulta y no en el fragmento:

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

Concesión de token sin ámbito openid

A continuación mostramos un ejemplo de solicitud que genera una concesión implícita y devuelve los JWT directamente a la sesión del usuario.

Ejemplo: Solicitud GET

La siguiente solicitud sirve para obtener una concesión implícita del servidor de autorización. El token de acceso de Amazon Cognito autoriza operaciones de la API 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
Ejemplo: Respuesta

El servidor de autorización de Amazon Cognito redirige a la aplicación con el 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. Amazon Cognito devuelve el token de acceso y el estado en el fragmento y no en la cadena de consulta:

HTTP/1.1 302 Found
Location: https://YOUR_APP/redirect_uri#access_token=ACCESS_TOKEN&token_type=bearer&expires_in=3600&state=STATE

Concesión de token con ámbito openid

A continuación mostramos un ejemplo de solicitud que genera una concesión implícita y devuelve los JWT directamente a la sesión del usuario.

Ejemplo: Solicitud GET

La siguiente solicitud sirve para obtener una concesión implícita del servidor de autorización. El token de acceso de Amazon Cognito autoriza el acceso a los atributos del usuario y a las operaciones de API 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
Ejemplo: Respuesta

El servidor de autorización redirige a la aplicación con el token de acceso y el token de ID (porque se ha incluido el ámbito openid):

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 autentica mediante una federación de IdP externos, es posible que Amazon Cognito sufra 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

  • En las autenticaciones realizadas mediante una federación de IdP externos, es posible que los proveedores 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