Se usó la API de Cloud Translation para traducir esta página.

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

Estás viendo la documentación de Apigee Edge.
Ve a la Documentación de Apigee X. información

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 y una descripción general del flujo de concesión de tipos de autorización de OAuth 2.0, y se explica cómo implementar este flujo en Apigee Edge.

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 funcional del tipo de otorgamiento de código de autorización en Apigee Edge en el repositorio api-platform-samples de GitHub. 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.

Pasos del flujo de código de autorización

Este es un resumen de los pasos necesarios para implementar el tipo de otorgamiento de código de autorización en el que Apigee Edge funciona como 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.

Requisitos: La app cliente debe estar registrada en Apigee Edge 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 (por ejemplo, una lista de contactos de un sitio de redes sociales), envía una llamada a la API a Apigee Edge, 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 ingresará 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.

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.

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

Si el acceso y el consentimiento se realizan correctamente, la app de acceso envía datos POST al /authorizationcode. extremo de Apigee Edge. 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 Edge genera un código de autorización

Cuando Edge recibe una solicitud GET de la app de acceso en el extremo /authorizationcode, se suceden las cosas. Primero, Edge determina que el acceso fue exitoso (comprobando el estado de HTTP o algún otro medio). Next Edge se asegura de que el URI de redireccionamiento enviado desde la app de acceso coincide con el URI de redireccionamiento que se especificó cuando se registró la app con Apigee Edge. Si todo está bien, Edge 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. Edge envía el código de autorización al cliente

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

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

Ahora, con un código de Auth válido, el cliente puede solicitar un token de acceso a Edge. Para ello, POST el ID de cliente y las claves secretas del cliente (obtenidas cuando la app se registró en Edge), la el tipo de otorgamiento y el alcance. Si incluyes el ID de cliente y las claves secretas, Apigee Edge puede verificar que la app cliente es 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 funciona correctamente, Edge 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 Edge (el proxy) y Edge 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, Edge debe procesar varias solicitudes de OAuth: para obtener acceso tokens de autenticación, códigos de autenticación, tokens de actualización, redireccionamientos de la página de acceso, etc. Hay dos pasos fundamentales para configura 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 “segmento” del flujo se define con un flujo en el proxy de Apigee Edge. 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. Para ejemplo, como se muestra en el siguiente XML, el extremo /oauth/authorizationcode tiene un asociada, llamada GenerateAuthCode (que es una política OAuthV2 con el una 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.

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 forma segura la app cliente acceda a sus recursos protegidos sin divulgar su nombre de usuario y contraseña a la aplicación cliente. Puedes lograr esto con una política de texto destacado de servicio, JavaScript, Node.js o por otros medios.

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. Edge verifica que cada solicitud tenga 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.