Usar tokens OAuth de terceros

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

Consulta la documentación de Apigee Edge.

En este tema, hablaremos sobre cómo importar tokens de acceso, tokens de actualización o códigos de autorización generados externamente al almacén de tokens de Apigee. Puedes usar esta técnica si quieres configurar Apigee para validar tokens que se generen fuera de Apigee.

En el caso habitual, Apigee generará y almacenará un token de OAuth, y lo devolverá a la aplicación que hace la llamada. La aplicación que llama presenta ese token a Apigee cuando solicita un servicio y Apigee, a través de la política OAuthV2 con Operation = VerifyAccessToken, verificará que el token sea válido. En este tema se describe cómo configurar Apigee para almacenar un token de OAuth que se haya generado en otro lugar, manteniendo la parte de verificación del token igual que si el token lo hubiera generado Apigee.

Ejemplo

Si quieres ver un ejemplo práctico que ilustre la técnica descrita en este tema, consulta el ejemplo de gestión de tokens delegada de Apigee.

¿Qué es esto?

Supongamos que tienes un sistema de autorización y quieres usar los valores de token o código generados por ese sistema en lugar de los valores de token o código de OAuth2 que genera Apigee. Después, puedes hacer solicitudes seguras de proxy de API con el token o el código sustituidos, y Apigee los validará como si los hubiera generado Apigee.

Información general

En el caso habitual, Apigee genera un token produciendo una cadena aleatoria de letras y números. Apigee asocia a ese token otros datos, como la hora en la que se emitió, la fecha de vencimiento, la lista de productos de API para los que es válido y el ámbito. Toda esta información se puede devolver en una respuesta generada automáticamente por la política OAuthV2 configurada con Operation = GenerateAccessToken. La respuesta tiene este aspecto:

{
  "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 de portador zBC90HhCGmGlaMBWeZAai2s3za5j. Con el valor del token, Apigee recupera los metadatos del token para determinar si es válido o no.

Si sigues los pasos que se describen en este artículo, puedes configurar Apigee para que almacene un token cuyo valor access_token haya generado un servicio externo. Por ejemplo, supongamos que tienes un sistema externo a Apigee que genera tokens con el formato "TOKEN-<16 números aleatorios>" . En ese caso, los metadatos completos del token almacenados por 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 aplicación podría hacer una solicitud a un proxy de API, que llevaría el token de portador TOKEN-1092837373654221, y Apigee podría 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 previo para generar un token es validar el cliente solicitante. De forma predeterminada, la política OAuthV2/GenerateAccessToken de Apigee verifica implícitamente las credenciales de cliente. Normalmente, en una solicitud de token OAuthV2, client_id y client_secret se transfieren en el encabezado Authorization, codificado mediante la autorización básica HTTP (concatenado con dos puntos y, a continuación, codificado en base64). La política OAuthV2/GenerateAccessToken de Apigee decodifica ese encabezado, busca el client_id y verifica que el client_secret proporcionado sea válido para ese client_id. Esto funciona si Apigee conoce las credenciales. En otras palabras, si hay una aplicación de desarrollador almacenada en Apigee que contiene una credencial, que a su vez contiene el client_id y el client_secret proporcionados.

Si Apigee no debe validar las credenciales de cliente, debes diseñar tu proxy de API para que valide explícitamente al cliente por otros medios antes de generar un token. A menudo, esto se hace a través de una política ServiceCallout que se conecta a un endpoint remoto de tu red.

De un modo u otro, ya sea de forma implícita o explícita, debes asegurarte de que el proxy de API que genera tokens valide primero las credenciales del cliente. Ten en cuenta que la validación del cliente es independiente de la generación del token de acceso. Puedes configurar Apigee para que haga ambas cosas, una u otra, o ninguna.

Si quieres que la política OAuthV2/GenerateAccessToken de Apigee valide las credenciales de cliente en el almacén de Apigee, define el elemento <ExternalAuthorization> en false en la configuración de la política u omítelo por completo. Si quieres usar un servicio de autorización externo para validar explícitamente las credenciales del cliente, asigna el valor true a <ExternalAuthorization>.

Aunque Apigee no valide las credenciales de cliente, sigue siendo necesario que Apigee conozca y gestione el client_id. Todos los access_token de Apigee, ya sean generados por Apigee o por un sistema externo y, a continuación, importados a Apigee, deben asociarse a una aplicación cliente, indicada por client_id. Por lo tanto, aunque la política OAuthV2/GenerateAccessToken de Apigee no valide que client_id y client_secret coincidan, sí validará que client_id sea válido, esté presente y no se haya revocado. Por lo tanto, como paso de configuración previo, es posible que tengas que importar client_id a través de la API administrativa de Apigee.

Flujo de políticas de OAuth de terceros en Apigee

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

External Validación de credenciales de cliente

  1. ServiceCallout para verificar las credenciales del cliente entrantes y obtener un token externo.
  2. ExtractVariables o un paso de JavaScript para extraer el token generado externamente de la respuesta.
  3. AssignMessage para definir la variable especial conocida como oauth_external_authorization_status. El valor debe ser true para indicar que las credenciales de cliente son válidas.
  4. OAuthV2/GenerateAccessToken con el elemento <ExternalAuthorization> definido como true y al menos uno de los elementos <ExternalAccessToken>, <ExternalRefreshToken> o <ExternalAuthorizationCode>.

Interna Validación de credenciales de cliente

  • ServiceCallout para adquirir un token externo.
  • ExtractVariables o un paso de JavaScript para extraer el token generado externamente de la respuesta.
  • OAuthV2/GenerateAccessToken con el elemento <ExternalAuthorization> definido como false y al menos uno de los elementos <ExternalAccessToken>, <ExternalRefreshToken> o <ExternalAuthorizationCode>.

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

  • Si quieres usar un sistema externo para validar las credenciales de cliente, debes desarrollar un flujo de políticas que haga lo que sea necesario. Normalmente, usarías una política ServiceCallout para enviar las credenciales reconocidas externamente al servicio de autenticación externo. El servicio de autenticación externo suele devolver una respuesta y, si las credenciales son válidas, también un token de acceso.

  • Después de ServiceCallout, el proxy de API debe analizar la respuesta para extraer el estado de validez, así como el token de acceso generado externamente y, posiblemente, el token de actualización.

  • En la política OAuthV2/GenerateAccessToken, asigna el valor true al elemento <StoreToken> y el valor true o false al elemento <ExternalAuthorization>, según corresponda.

    Cuando se ejecuta la política OAuthV2/GenerateAccessToken, lee la variable oauth_external_authorization_status. Si la variable está definida y el valor es true, Apigee no intentará validar las credenciales del cliente. Si la variable no se define o el valor no es true, Apigee intentará validar las credenciales del cliente.

  • La política OAuthV2 tiene tres elementos que te permiten especificar los datos externos que quieres importar: <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, el token de actualización o el código de autorización generados externamente. Es tu responsabilidad implementar políticas y lógica para colocar los tokens o códigos externos en las variables adecuadas.

    Por ejemplo, la siguiente configuración de la política OAuthV2 indica a Apigee que busque el token en una variable de contexto llamada external_token.

    <ExternalAccessToken>external_token</ExternalAccessToken>

    También necesitarías un paso anterior que definiera esa variable.

  • En cuanto a la configuración de la variable oauth_external_authorization_status, una técnica habitual para definir esta variable es usar una política 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 aplicarse antes que la política OAuthV2 con Operation = GenerateAccessToken.

Ejemplo de política OAuthV2

La siguiente política OAuthV2 genera un token de acceso si 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>

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