Estás consultando la documentación de Apigee Edge.
Consulta la
documentación de Apigee X. Información
Con el tipo de otorgamiento de credenciales de cliente, una app envía sus propias credenciales (el ID de cliente y el secreto del cliente) a un extremo en Apigee Edge que está configurado para generar un token de acceso. Si las credenciales son válidas, Edge muestra un token de acceso a la app cliente.
Acerca de este tema
En este tema, se ofrece una descripción general del tipo de otorgamiento de credenciales de cliente de OAuth 2.0 y se analiza cómo implementar este flujo en Apigee Edge.
Casos de uso
En general, este tipo de otorgamiento se usa cuando la app también es el propietario del recurso. Por ejemplo, es posible que una app necesite acceder a un servicio de almacenamiento basado en la nube de backend a fin de almacenar y recuperar datos que utiliza para realizar su trabajo, en lugar de datos específicos del usuario final. Este flujo de tipo de otorgamiento se lleva a cabo estrictamente entre una app cliente y el servidor de autorización. Un usuario final no participa en este flujo de tipo de otorgamiento.
Funciones
Las funciones especifican los "actores" que participan en el flujo de OAuth. Analicemos una descripción general de las funciones de las credenciales de cliente para ilustrar el lugar en el que encaja Apigee Edge. Para ver un análisis completo de las funciones de OAuth 2.0, consulta la especificación de OAuth 2.0 de IETF.
- App cliente: la app que necesita acceder a los recursos protegidos del usuario. Por lo general, con este flujo, la app se ejecuta en el servidor en lugar de localmente en la laptop o el dispositivo del usuario.
- Apigee Edge: En este flujo, Apigee Edge es el servidor de autorización de OAuth. Su función es generar tokens de acceso, validar tokens de acceso y pasar solicitudes autorizadas para recursos protegidos al servidor de recursos.
- Servidor de recursos: el servicio de backend que almacena los datos protegidos a los que necesita acceder la app cliente. Si proteges los proxies de API alojados en Apigee Edge, este también es el servidor de recursos.
Muestra de código
Puedes encontrar una implementación de muestra completa y funcional del tipo de otorgamiento de credenciales de cliente en GitHub. Consulta la sección Recursos adicionales a continuación para ver vínculos a más ejemplos.
Diagrama de flujo.
En el siguiente diagrama de flujo, se ilustra el flujo de credenciales del cliente en el que Apigee Edge sirve como servidor de autorización. En general, Edge también es el servidor de recursos en este flujo, es decir, los proxies de API son los recursos protegidos.
Pasos del flujo de credenciales de cliente
Este es un resumen de los pasos necesarios para implementar el tipo de otorgamiento de código de credenciales del cliente en el que Apigee Edge funciona como servidor de autorización. Recuerda que, con este flujo, la app cliente solo presenta su ID de cliente y el secreto del cliente y, si son válidos, Apigee Edge muestra un token de acceso.
Requisito: La app cliente debe estar registrada en Apigee Edge para obtener el ID y las claves secretas del cliente. Consulta Cómo registrar apps cliente para obtener más detalles.
1. El cliente solicita un token de acceso
Para recibir un token de acceso, el cliente realiza una POST de una llamada a la API para Edge con los valores del ID y el secreto del cliente obtenidos de una app de desarrollador registrada. Además, el parámetro otorga_type=client_credentials debe pasarse como parámetro de consulta. (Sin embargo, puedes configurar la política OAuthV2 para aceptar este parámetro en el encabezado o el cuerpo de la solicitud; consulta la política de OAuthV2 para obtener más información).
Por ejemplo:
$ curl -i -H 'Content-Type: application/x-www-form-urlencoded' -X POST 'https://docs-test.apigee.net/oauth/accesstoken' -d 'grant_type=client_credentials&client_id=ns4fQc14Zg4hKFCNaSzArVuwszX95X&client_secret=ZIjFyTsNgQNyxI'
Nota: Si bien puedes pasar los valores client_id y client_secret como parámetros de consulta como se muestra arriba, se recomienda pasarlos como una string codificada como URL base64 en el encabezado de autorización. Para ello, debes usar una herramienta o utilidad de codificación Base64 a fin de codificar los dos valores junto con dos puntos separados. De esta manera: aBase64EncodeFunction(clientidvalue:clientsecret). Por lo tanto, el ejemplo anterior se codificaría de la siguiente manera:
Resultado = aBase64EncodeFunction(ns4fQc14Zg4hKFCNaSzArVuwszX95X:ZIjFyTsNgQNyxI) // Ten en cuenta los dos puntos que separan los dos valores.
El resultado de la codificación en base64 de la string anterior es: bnM0ZlFjMTRaZzRoS0ZDTmFTekFyVnV3c3pYOTVYOlpJakZ5VHNOZ1FOeXhJOg==
Luego, realiza la solicitud del token de la siguiente manera:
$ curl -i -H 'Content-Type: application/x-www-form-urlencoded' -X POST 'https://docs-test.apigee.net/oauth/accesstoken' -d 'grant_type=client_credentials' -H 'Authorization: Basic bnM0ZlFjMTRaZzRoS0ZDTmFTekFyVnV3c3pYOTVYOlpJakZ5VHNOZ1FOeXhJOg=='
2. Edge valida las credenciales.
Ten en cuenta que la llamada a la API se envía al extremo /accesstoken. Este extremo tiene una política adjunta que valida las credenciales de la app. Es decir, la política compara las claves enviadas con las que creó Apigee Edge cuando se registró la app. Si quieres obtener más información sobre los extremos de OAuth en Edge, consulta Configura extremos y políticas de OAuth.
3. Edge muestra una respuesta
Si las credenciales están bien, Edge muestra un token de acceso al cliente. De lo contrario, se muestra un error.
4. El cliente llama a la API protegida
Ahora, con un token 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. Para ver un ejemplo, consulta Llama a la API protegida a continuación.
Configura flujos y políticas
Como servidor de autorización, Edge procesa las solicitudes de tokens de acceso. Como desarrollador de API, debes crear un proxy con un flujo personalizado para manejar las solicitudes de tokens y agregar y configurar una política de OAuthV2. En esta sección, se explica cómo configurar ese extremo.
Configuración de flujo personalizado
La manera más fácil de mostrar cómo está configurado el flujo de proxy de API es mostrar la definición de flujo XML. Aquí te mostramos un ejemplo de flujo de proxy de API diseñado para procesar una solicitud de token de acceso. Por ejemplo, cuando llega una solicitud y el sufijo de la ruta de acceso coincide con /accesstoken, se activa la política GetAccessToken. Consulta Configura extremos y políticas de OAuth a fin de obtener una descripción general rápida de los pasos necesarios para crear un flujo personalizado como este.
<Flows>
<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>GetAccessToken</Name></Step>
</Request>
</Flow>
</Flows>
Configura el flujo con una política
Debes adjuntar una política al extremo de la siguiente manera. Consulta Cómo configurar extremos y políticas de OAuth para obtener una descripción general de los pasos necesarios y agregar una política de OAuthV2 a un extremo del proxy.
Obtén un token de acceso
Esta política se adjunta a la ruta de acceso /accesstoken. Usa la política de OAuthV2 con la operación GenerateAccessToken especificada.
<OAuthV2 name="GetAccessToken">
<Operation>GenerateAccessToken</Operation>
<ExpiresIn>3600000</ExpiresIn>
<SupportedGrantTypes>
<GrantType>client_credentials</GrantType>
</SupportedGrantTypes>
<GenerateResponse/>
</OAuthV2>
La llamada a la API para obtener el token de acceso es un POST y, además, incluye un encabezado de autorización con el client_id + el cliente+secreto codificado en base64 y el parámetro de consulta allow_type=client_credentials. También puede incluir parámetros opcionales para el alcance y el estado. Por ejemplo:
$ curl -i -H 'Content-Type: application/x-www-form-urlencoded' -X POST 'https://docs-test.apigee.net/oauth/accesstoken' -d 'grant_type=client_credentials' -H 'Authorization: Basic c3FIOG9vSGV4VHo4QzAySVgT1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ'
Adjunta la política de verificación de token de acceso
Para proteger tu API con la seguridad de OAuth 2.0, debes agregar una política de OAuthV2 con la operación VerifyAccessToken. Esta política comprueba que las solicitudes entrantes tengan un token de acceso válido. Si el token es válido, Edge procesa la solicitud. Si no es válida, Edge mostrará un error. Para ver 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.
Recursos adicionales
- Apigee ofrece capacitación en línea para desarrolladores de API, incluido un curso sobre la seguridad de API, que incluye OAuth.
- Política de OAuthV2: Tiene muchos ejemplos que muestran cómo realizar solicitudes al servidor de autorización y cómo configurar la política de OAuthV2.