Usa tokens de OAuth de terceros

Esta página se aplica a Apigee y Apigee Hybrid.

Consulta la documentación de Apigee Edge.

En este tema, analizaremos cómo importar tokens de acceso generados de forma externa, tokens de actualización o códigos de autenticación al almacén de tokens de Apigee. Puedes usar esta técnica si deseas configurar Apigee para validar tokens que se generan fuera de Apigee.

En el caso usual, Apigee generará y almacenará un token de OAuth y lo mostrará en la aplicación que realiza la llamada. La app que realiza la llamada presenta ese token a Apigee cuando se solicita el servicio, y Apigee, a través de la política de OAuthV2 con Operation = VerifyAccessToken, verificará que el token sea válido. En este tema, se describe cómo puedes configurar Apigee para almacenar un token de OAuth que se generó en otro lugar, mientras se mantiene la misma parte de la verificación de token, como si Apigee lo generara.

Ejemplo

Si deseas ver un ejemplo funcional en el que se ilustra la técnica descrita en este tema, consulta la muestra de administración de tokens delegados de Apigee.

¿Qué es esto?

Supongamos que tienes un sistema de autorización existente y deseas usar el token o los valores de código que genera ese sistema en lugar del token de OAuth2 o los valores de código que genera Apigee. Luego, puedes hacer solicitudes de proxy de API seguras con el token o el código sustituidos, y Apigee los validará como si los generara.

Información general

En el caso habitual, Apigee genera un token mediante una producción de string aleatoria de letras y números. Apigee asocia a ese token, otros datos, como la hora en que se emitió el token, el vencimiento, la lista de productos de API para los que el token y el permiso son válidos. Toda esta información se puede mostrar en una respuesta la política de OAuthV2 configuró de forma automática con la operación = GenerateAccessToken. La respuesta es similar a la que se muestra a continuación:

{
  "issued_at": "1469735625687",
  "application_name": "06947a86-919e-4ca3-ac72-036723b18231",
  "scope": "urn://example.com/read",
  "status": "approved",
  "api_product_list": "[implicit-test]",
  "api_product_list_json": ["implicit-test"],
  "expires_in": "1799", //--in seconds
  "developer.email": "joe@weathersample.com",
  "token_type": "BearerToken",
  "client_id": "U9AC66e9YFyI1yqaXgUF8H6b9wUN1TLk",
  "access_token": "zBC90HhCGmGlaMBWeZAai2s3za5j",
  "organization_name": "myorg",
  "refresh_token_expires_in": "0", //--in seconds
  "refresh_count": "0"
}

Apigee usa el valor access_token para recuperar los metadatos del token. Por ejemplo, supongamos que una solicitud de proxy de API incluye el token del portador zBC90HhCGmGlaMBWeZAai2s3za5j. Mediante el valor del token, Apigee recupera los metadatos del token para determinar si este es válido o no.

Si sigues los pasos que se describen aquí, puedes configurar Apigee para que almacene un token cuyo valor access_token un servicio externo genera. Por ejemplo, supongamos que tienes un sistema externo a Apigee que genera tokens con el formato “TOKEN-<16 números al azar>”. En ese caso, los metadatos del token completos que almacena Apigee podrían ser los siguientes:

{
  "issued_at": "1469735625687",
  "application_name": "06947a86-919e-4ca3-ac72-036723b18231",
  "scope": "urn://example.com/read",
  "status": "approved",
  "api_product_list": "[implicit-test]",
  "api_product_list_json": ["implicit-test"],
  "expires_in": "1799", //--in seconds
  "developer.email": "joe@weathersample.com",
  "token_type": "BearerToken",
  "client_id": "U9AC66e9YFyI1yqaXgUF8H6b9wUN1TLk",
  "access_token": "TOKEN-1092837373654221",
  "organization_name": "myorg",
  "refresh_token_expires_in": "0", //--in seconds
  "refresh_count": "0"
}

En este caso, una app podría realizar una solicitud a un proxy de API, con el token del portador TOKEN-1092837373654221, y Apigee podrá validarlo. Puedes aplicar un patrón de importación similar a los códigos de autorización y a los tokens de actualización.

Hablemos sobre la validación de credenciales de cliente

Un requisito para generar un token es validar el cliente solicitante. De forma predeterminada, la política OAuthV2/GenerateAccessToken en Apigee verifica implícitamente las credenciales de cliente. Por lo general, en una solicitud de un token OAuthV2, client_id y client_secret se pasan en el encabezado de autorización, codificado mediante autorización básica HTTP (concatenado con dos puntos y codificado en base64). La política OAuthV2/GenerateAccessToken en Apigee decodifica ese encabezado y busca el client_id y verifica que el client_secret que se pasó sea válido para ese client_id. Esto funciona si Apigee conoce las credenciales; en otras palabras, hay una app de desarrollador almacenada en Apigee que contiene una credencial, que tiene el client_id y client_secret determinados.

En el caso de que Apigee no valide las credenciales del cliente, debes diseñar tu proxy de API antes de generar un token para validar al cliente de forma explícita a través de otros medios. A menudo, esto se hace a través de una política de ServiceCallout que se conecta a un extremo remoto en tu red.

Una o ambas, ya sea de forma implícita o explícita, debes asegurarte de que el proxy de API que genera tokens primero valide las credenciales de cliente. Ten en cuenta que validar el cliente es independiente de la generación del token de acceso. Puedes configurar Apigee a fin de que haga ambas tareas, o bien para que realice una de las dos o ninguna.

Si deseas que la política OAuthV2/GenerateAccessToken en Apigee valide las credenciales de cliente en el almacén de Apigee, configura el elemento <ExternalAuthorization> como false dentro de la configuración de la política o, en su lugar, ignóralo por completo. Si deseas usar un servicio de autorización externo para validar de forma explícita las credenciales del cliente, establece <ExternalAuthorization> como true.

Aunque es posible que Apigee no valide las credenciales del cliente, aún es necesario que Apigee conozca y administre client_id. Cada access_token en Apigee, ya sea generado por Apigee o por un sistema externo y luego importado a Apigee, debe estar asociado a una aplicación cliente, indicada por client_id. Entonces, incluso en el caso de que la política OAuthV2/GenerateAccessToken en Apigee no valide que client_id y client_secret coincidan, la política validará que client_id sea válido, esté presente y no esté revocado. Por lo tanto, como requisito previo de la configuración, es posible que debas importar los client_id mediante la API administrativa de Apigee.

Flujo de políticas para OAuth de terceros en Apigee

A fin de usar tokens de sistemas OAuth de terceros en Apigee, el flujo para generar tokens de acceso debe seguir uno de los siguientes patrones.

Validación externa de credenciales de cliente

ServiceCallout para verificar las credenciales del cliente entrante y adquirir un token externo.
ExtractVariables o un paso de JavaScript para extraer el token generado de forma externa a partir de la respuesta.
AssignMessage para establecer la variable especial conocida llamada oauth_external_authorization_status. El valor debe ser verdadero para indicar que las credenciales del cliente son válidas.
OAuthV2/GenerateAccessToken con el elemento <ExternalAuthorization> configurado como true y al menos uno de <ExternalAccessToken>, <ExternalRefreshToken> o <ExternalAuthorizationCode>.

Validación interna de las credenciales de cliente

ServiceCallout para adquirir un token externo.
ExtractVariables o un paso de JavaScript para extraer el token generado de forma externa a partir de la respuesta.
OAuthV2/GenerateAccessToken con el elemento <ExternalAuthorization> configurado como false y al menos uno de <ExternalAccessToken>, <ExternalRefreshToken> o <ExternalAuthorizationCode>.

Notas sobre la configuración de políticas y el flujo

En el caso de que desees usar un sistema externo para validar credenciales de cliente, depende de ti desarrollar un flujo de políticas que haga lo que sea necesario. Por lo general, usarías una política ServiceCallout para enviar las credenciales reconocidas externamente al servicio de autenticación externo. Por lo general, el servicio de autenticación externo muestra una respuesta y, si las credenciales son válidas, también un token de acceso.
Después de ServiceOverflow, el proxy de la API debe analizar la respuesta para extraer el estado de validez, así como el acceso_token generado de manera externa y posiblemente el refresh_token.
En la política OAuthV2/GenerateAccessToken, configura el elemento <StoreToken> como true y configura el elemento <ExternalAuthorization> como true o false según corresponda.

Cuando se ejecuta la política OAuthV2/GenerateAccessToken, se lee la variable oauth_external_authorization_status. Si la variable está configurada y el valor es verdadero, Apigee no intenta validar las credenciales de cliente. Si no se configuró la variable o el valor no es verdadero, Apigee intentará validar las credenciales de cliente.
La política de OAuthV2 tiene tres elementos que te permiten especificar los datos externos que se importarán: <ExternalAccessToken>, <ExternalRefreshToken> y <ExternalAuthorizationCode>. Cada uno de estos elementos acepta una variable de flujo. La política de Apigee leerá esa variable para encontrar el token de acceso generado de forma externa, el token de actualización o el código de autorización. Depende de ti implementar políticas y lógica para colocar los tokens o códigos externos en las variables adecuadas.

Por ejemplo, la siguiente configuración en la política OAuthV2 le indica a Apigee que busque el token en una variable de contexto llamada external_token.
```
<ExternalAccessToken>external_token</ExternalAccessToken>
```
También necesitarías tener un paso anterior que establezca esa variable.
En cuanto a la configuración de la variable oauth_external_authorization_status, una técnica común para configurar esta variable es usar una política de AssignMessage con el elemento AssignVariable, como se muestra a continuación:
```
<AssignMessage name="AssignMessage-SetVariable">
    <DisplayName>Assign Message - Set Variable</DisplayName>
    <AssignVariable>
        <Name>oauth_external_authorization_status</Name>
        <Value>true</Value>
    </AssignVariable>
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</AssignMessage>
```
Recuerda que esta política debe ser anterior a la política de OAuthV2 con Operation = GenerateAccessToken.

Ejemplo de política de OAuthV2

En la siguiente política de OAuthV2, se genera un token de acceso determinado en el que Apigee encuentra un valor de token en la variable de flujo external_access_token.

<OAuthV2 name="OAuth-v20-Store-External-Token">
    <DisplayName>OAuth v2.0 1</DisplayName>
    <Attributes/>
    <ExternalAccessToken>external_access_token</ExternalAccessToken>
    <ExternalAuthorization>true</ExternalAuthorization>
    <Operation>GenerateAccessToken</Operation>
    <GenerateResponse enabled="true">
        <Format>FORM_PARAM</Format>
    </GenerateResponse>
    <ReuseRefreshToken>false</ReuseRefreshToken>
    <StoreToken>true</StoreToken>
    <SupportedGrantTypes>
        <GrantType>client_credentials</GrantType>
    </SupportedGrantTypes>
    <ExpiresIn ref='flow.variable'>2400000</ExpiresIn>
</OAuthV2>

Por lo general, con el tipo de otorgamiento de credenciales de cliente, debes proporcionar un encabezado de autenticación básica con el ID de cliente codificado y el secreto del cliente. Sin embargo, en este caso, no necesitas proporcionar ese encabezado. La política aún espera que el client_id esté presente en la solicitud, y la política la validará. Apigee espera que client_id se envíe como parte de los datos del formulario de solicitud, p. ej., en request.formparam.client_id.

En teoría, podrías aplicar este patrón con cualquier servicio de autorización de OAuth2 de terceros.