Cómo implementar el tipo de otorgamiento de código de autorización

Estás viendo la documentación de Apigee X.
Consulta la documentación de Apigee Edge.

El código de autorización es uno de los tipos de subvención de OAuth 2.0 más usados. El flujo de código de autorización es una configuración de OAuth de tres segmentos. En esta configuración, el usuario se autentica junto con el servidor de recursos y da al consentimiento de la app el acceso a sus recursos protegidos sin delegar el nombre de usuario/contraseña a la app cliente.

Acerca de este tema

En este tema, se ofrece una descripción general del flujo de otorgamiento de autorización de OAuth 2.0 y se explica cómo implementar este flujo en Apigee.

Video

Mira un video breve para aprender a usar el tipo de otorgamiento de autorización de OAuth 2.0 con el fin de asegurar tus API.

Casos prácticos

Este tipo de otorgamiento está destinado a aplicaciones escritas por desarrolladores externos que no tienen una relación comercial de confianza con el proveedor de API. Por ejemplo, los desarrolladores que se registran para programas de API públicas no suelen ser de confianza. Con este tipo de concesión, las credenciales del usuario en el servidor de recursos nunca se comparten con la app.

Muestra de código

Puedes encontrar una implementación de muestra completa y en funcionamiento del tipo de otorgamiento de código de autorización en Apigee en el repositorio api-platform-samples. Consulta el ejemplo de oauth-advanced en el directorio api-platform-samples/sample-proxies. Consulta el archivo README para obtener detalles sobre la muestra.

Diagrama de flujo

El siguiente diagrama de flujo ilustra el flujo de OAuth de código de autorización con Apigee Edge que funciona como servidor de autorización.

Sugerencia: A fin de ver una versión más grande de este diagrama, haz clic con el botón derecho para abrirlo en una pestaña nueva. También puedes guardarlo y abrirlo en un visor de imágenes.

Flujo de OAuth de código de autorización

Pasos del flujo de código de autorización

Aquí hay un resumen de los pasos requeridos para implementar el tipo de otorgamiento de código de autorización en el que Apigee es el servidor de autorización. Recuerda que la clave de este flujo es que el cliente nunca verá las credenciales del usuario en el servidor de recursos.

Requisito: La app cliente debe estar registrada en Apigee para obtener el ID de cliente y las claves del secreto del cliente. Consulta Cómo registrar apps cliente para obtener más detalles.

1. El usuario inicia el flujo

Cuando la app necesita acceder a los recursos protegidos del usuario desde un servidor de recursos (por ejemplo, la lista de contactos en un sitio de redes sociales), envía una llamada a la API a Apigee, que valida el ID de cliente y, si es válido, redirecciona el navegador del usuario a una página de acceso en la que el usuario ingresa sus credenciales. La llamada a la API incluye información que la app cliente obtuvo cuando se registró: el ID de cliente y el URI de redireccionamiento.

2. El usuario ingresa las credenciales

El usuario ahora verá una página de acceso donde se le pedirá que ingrese sus credenciales de acceso. Si el acceso se ejecuta de forma correcta, vamos al paso siguiente.

Página de acceso de Apigee con campos de dirección de correo electrónico y contraseña.

3. El usuario da su consentimiento

En este paso, el usuario da su consentimiento a la aplicación para acceder a sus recursos. El formulario de consentimiento generalmente incluye selecciones de alcance, en las que el usuario puede elegir lo que la app puede hacer en el servidor de recursos. Por ejemplo, el usuario puede otorgar permiso de solo lectura o permiso para que la app actualice los recursos.

Página de consentimiento en la que la app de muestra solicita el pedido de botones Permitir y Rechazar.

4. La app de acceso envía una solicitud a Apigee

Si el acceso y el consentimiento se ejecutan correctamente, la aplicación de acceso transmite datos al extremo /authorizationcode de Apigee. Los datos incluyen el URI de redireccionamiento, el ID de cliente, el permiso, toda la información específica del usuario que desea incluir y la indicación de que el acceso fue exitoso.

5. Apigee genera un código de autorización

Cuando Apigee recibe una solicitud GET de la aplicación de acceso en su extremo /authorizationcode, se producen dos situaciones. Primero, Apigee determina que el acceso se realizó correctamente (mediante la comprobación el estado HTTP o algún otro medio). A continuación, Apigee comprueba que el URI de redireccionamiento enviado desde la aplicación de acceso coincide con el URI de redireccionamiento que se especificó cuándo se registró la aplicación con Apigee. Si todo está bien, Apigee genera un código de autorización. Por ejemplo:

http://myorg-test.apigee.net/oauth/authorizationcode?client_id={consumer_key}&response_type=code&redirect_uri={redirect_uri}&scope=scope1%20scope2&state={some_string}

6. Apigee envía el código de autorización al cliente

Apigee envía un redireccionamiento 302 con el código de autenticación adjunto como un parámetro de consulta al cliente.

7. El cliente recupera el código de autorización y solicita un código de acceso de Apigee

Ahora, con un código de autenticación válido, el cliente puede solicitar un token de acceso de Apigee. Para hacerlo, debes PUBLICAR el ID de cliente y sus claves secretas (obtenidas cuando la app se registró en Apigee), el tipo de otorgamiento y el permiso. Cuando se incluye el ID de cliente y las claves secretas, Apigee puede verificar que la aplicación cliente sea la que se registró. Por ejemplo:

$ curl https://{org_name}-test.apigee.net/my_oauth_proxy/accesstoken?code=Xyz123&grant_type=authorization_code -X POST -d 'client_id=bBGAQrXgivA9lKu7NMPyoYpKNhGar6K&client_secret=hAr4GngA9vAyvI4'

8. El cliente recibe un token de acceso

Si todo se ejecuta de forma correcta, Apigee muestra un token de acceso al cliente. El token de acceso tendrá un vencimiento y solo será válido para el alcance que especifique el usuario cuando dio su consentimiento para que la app acceda a sus recursos.

9. El cliente llama a la API protegida

Ahora, con un código de acceso válido, el cliente puede realizar llamadas a la API protegida. En este caso, las solicitudes se realizan a Apigee (el proxy) y Apigee es responsable de validar el token de acceso antes de pasar la llamada a la API al servidor de recursos de destino. Los tokens de acceso se pasan en un encabezado de autorización. Por ejemplo:

$ curl -H "Authorization: Bearer ylSkZIjbdWybfs4fUQe9BqP0LH5Z" http://{org_name}-test.apigee.net/weather/forecastrss?w=12797282

Configura flujos y políticas

Como servidor de autorización, Apigee debe procesar varias solicitudes OAuth: para tokens de acceso, códigos de autenticación, tokens de actualización, redireccionamientos de página de acceso, etc. Hay dos pasos fundamentales para configurar estos extremos:

  • Crea flujos personalizados
  • Agrega y configura políticas de OAuthV2

Configuración de flujo personalizado

Por lo general, configuras este flujo de tipo de otorgamiento para que cada paso o leg del flujo lo defina un flujo en el proxy de Apigee. Cada flujo tiene un extremo y una política que realiza la tarea específica de OAuth requerida, como generar un código de autorización o un token de acceso. Por ejemplo, como se muestra en el siguiente XML, el extremo /oauth/authorizationcode tiene una política asociada llamada GenerateAuthCode (que es una política de OAuthV2 con la operación GenerateAuthorizationCode especificada).

La manera más fácil de mostrar la configuración de flujo es con un ejemplo de XML. Consulta los comentarios en línea para obtener información sobre cada flujo. Este es un ejemplo: los nombres de flujos y rutas se pueden configurar de la forma que quieras. Consulta también Configura extremos y políticas de OAuth para obtener una descripción general de los pasos necesarios y crear un flujo personalizado como este.

Consulta también la implementación de ejemplo en GitHub.

<Flows>
<Flow name="RedirectToLoginApp">
<!--
Publish this URI to developers to use for their 'login' link
-->
<Condition>proxy.pathsuffix == "/oauth/authorize"</Condition>
<Request>
<Step><Name>RedirectToLoginPage</Name></Step>
</Request>
</Flow>
<Flow name="GetAuthCode">
<!--
Call this URL from your Login app after you authenticate the user.
The policy will automatically return the auth code in the response to the
redirect_uri registered by the calling app
-->
<Condition>proxy.pathsuffix == "/oauth/authorizationcode"</Condition>
<Request>
<Step><Name>GenerateAuthCode</Name></Step>
</Request>
</Flow>
<Flow name="GetAccessToken">
<!-- This policy flow is triggered when the URI path suffix
matches /oauth/accesstoken. Publish this URL to app developers
to use when obtaining an access token using an auth code
-->
<Condition>proxy.pathsuffix == "/oauth/accesstoken"</Condition>
<Request>
<Step><Name>GenerateAccessToken</Name></Step>
</Request>
</Flow>
</Flows>

Configura los flujos con políticas

Cada extremo tiene una política asociada. Veamos los ejemplos de las políticas. Consulta también Configura extremos y políticas de OAuth para obtener una descripción general de los pasos necesarios a fin de agregar políticas de OAuthV2 a extremos de proxy.

Redireccionamiento de acceso

Esta es la ruta de acceso /oauth/authorize. La política adjunta es responsable de redireccionar al usuario a una app de acceso, en la que el usuario final puede autenticar y autorizar de manera segura a la app cliente para que acceda a sus recursos protegidos sin divulgar su nombre de usuario y contraseña a la app cliente. Puedes hacerlo con una política de texto destacado de servicio, JavaScript o cualquier otro medio.

La llamada a la API que se realiza es una solicitud GET y requiere los parámetros query_id, response_type, redirect_uri, permiso y estado.

$ curl http://myorg-test.apigee.net/oauth/authorize?client_id={consumer_key}&response_type=code&redirect_uri={redirect_uri}&scope=scope1%20scope2&state={some_string}

Obtener código de autenticación

Esta es la ruta de acceso /oauth/authorizationcode. Usa la política de OAuthV2 con la operación GenerateAuthorizationCode especificada.

<OAuthV2 async="false" continueOnError="false" enabled="true" name="GetAuthCode">
    <DisplayName>GetAuthCode</DisplayName>
    <Operation>GenerateAuthorizationCode</Operation>
    <ExpiresIn>600000</ExpiresIn>
    <GenerateResponse/>
</OAuthV2>

La llamada a la API para obtener el código de autorización es un GET y requiere los parámetros de consulta client_id, response_type, y, opcionalmente, el permiso y el estado, como se muestra en este ejemplo:

$curl http://myorg-test.apigee.net/oauth/authorizationcode?client_id={consumer_key}&response_type=code&scope=scope1%20scope2&state={some_string}

Obtén un token de acceso

Esta política se adjunta a la ruta de acceso /oauth/accesstoken. Usa la política de OAuthV2 con la operación GenerateAccessCode especificada. En este caso, se espera el parámetro grants_type como parámetro de consulta:

<OAuthV2 name="GetAccessToken">
    <Operation>GenerateAccessToken</Operation>
    <ExpiresIn>360000000</ExpiresIn>
    <SupportedGrantTypes>
        <GrantType>authorization_code</GrantType>
    </SupportedGrantTypes>
    <GrantType>request.queryparam.grant_type</GrantType>
    <GenerateResponse/>
</OAuthV2>

La llamada a la API para obtener el código de acceso es un POST y debe incluir el client_id, client_secret, grants_type=authorization_code y, opcionalmente, el permiso. Por ejemplo:

$ curl https://{org_name}-test.apigee.net/oauth/accesstoken?grant_type=authorization_code -X POST -d 'client_id=bBGAQrXgivA9lKu7NMPyoYpVKNhGar6K&client_secret=hAr4Gn0gA9vAyvI4'

Este es solo un resumen básico. Un ejemplo de producción incluye muchas otras políticas para compilar URL, realizar transformaciones y realizar otras tareas. Consulta la muestra de GitHub para obtener un proyecto completo que funcione.

Adjunta la política de verificación de token de acceso

Adjunta una política VerifyAccessToken (política OAuthV2 con la operación VerifyAccessToken especificada) al comienzo de cualquier flujo que acceda a una API protegida para que se ejecute cada vez que reciba una solicitud de recursos protegidos. Apigee verifica que cada solicitud tenga un token de acceso válido. De lo contrario, se muestra un error. Para conocer los pasos básicos, consulta Verifica tokens de acceso.

<OAuthV2 async="false" continueOnError="false" enabled="true" name="VerifyAccessToken">
    <DisplayName>VerifyAccessToken</DisplayName>
    <ExternalAuthorization>false</ExternalAuthorization>
    <Operation>VerifyAccessToken</Operation>
    <SupportedGrantTypes/>
    <GenerateResponse enabled="true"/>
    <Tokens/>
</OAuthV2>

Cómo llamar a la API protegida

Para llamar a una API protegida con la seguridad de OAuth 2.0, debes presentar un token de acceso válido. El patrón correcto es incluir el token en un encabezado de autorización de la siguiente manera (ten en cuenta que el token de acceso también se conoce como token del portador):

$ curl -H "Authorization: Bearer UAj2yiGAcMZGxfN2DhcUbl9v8WsR" \
  http://myorg-test.apigee.net/v0/weather/forecastrss?w=12797282

Consulta también Envía un token de acceso.