Usa tokens de OAuth de terceros

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

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

En el caso habitual, Apigee Edge generará y almacenará un token de OAuth, y lo mostrará en la aplicación que realiza la llamada. Luego, la app que realiza la llamada presenta ese token a Apigee Edge cuando solicita el servicio, y Apigee Edge, a través de la política OAuthV2 con Operación = VerifyAccessToken, verificará que el token sea válido. En este tema, se describe cómo configurar Apigee Edge para almacenar un token de OAuth que se generó en otro lugar y, al mismo tiempo, mantener la parte de la verificación del token igual, como si Edge 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 ya tienes un sistema de autorización y deseas usar los valores de token o de código que genera ese sistema en lugar de los valores de token o código de OAuth2 que genera Edge. Luego, puedes realizar solicitudes seguras de proxy de API con el token o código sustituido, y Edge las validará como si las hubiera generado Edge.

Información general

En el caso habitual, Apigee Edge genera un token mediante la producción de una cadena aleatoria de letras y números. Apigee Edge asocia a ese token otros datos, como la hora de emisión del token, el vencimiento, la lista de productos de la API para los que el token es válido y el alcance. 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": "wwitman",
  "refresh_token_expires_in": "0", //--in seconds
  "refresh_count": "0"
}

El valor del atributo access_token es, en efecto, la clave de búsqueda de los datos de respuesta. Una app podría realizar una solicitud a un proxy de API alojado en Edge, con el token del portador zBC90HhCGmGlaMBWeZAai2s3za5j, y Edge (con la política OAuthV2 con Operation = VerifyAccessToken) buscará el token, recuperará toda la información y la usará a fin de determinar si el token es válido o no para el proxy de API solicitado. Esto se denomina validación de token. Toda la información anterior comprende el token. El valor access_token es solo la manera de buscar esa información.

Por otro lado, si sigues los pasos que se describen aquí, puedes configurar Edge para que almacene un token de modo que su valor access_token sea algo generado por un servicio externo. Todos los demás metadatos pueden ser iguales. Por ejemplo, supongamos que tienes un sistema externo a Apigee Edge que genera tokens con el formato “TOKEN-<16 random number>" . En ese caso, los metadatos completos del token que almacena Apigee Edge 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": "wwitman",
  "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 alojado en Edge, con el token del portador TOKEN-1092837373654221, y Edge, mediante la política OAuthV2 con Operation = VerifyAccessToken, 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 Edge verifica implícitamente las credenciales de cliente. Por lo general, en una solicitud de un token OAuthV2, el client_id y client_secret se pasan en el encabezado de autorización, codificados a través de la autorización básica HTTP (concatenados entre dos puntos y, luego, codificados en base64). La política OAuthV2/GenerateAccessToken en Apigee Edge decodifica ese encabezado, busca el customer_id y verifica que el client_secret que se pasó sea válido para ese client_id. Esto funciona si Apigee Edge conoce las credenciales. En otras palabras, hay una app de desarrollador almacenada en Apigee Edge que contiene una credencial que contiene los client_id y client_secret dados.

En el caso de que Apigee Edge no valide las credenciales del cliente, debes diseñar tu proxy de API, antes de que genere un token, para validar explícitamente el cliente 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.

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

Si deseas que la política OAuthV2/GenerateAccessToken en Apigee Edge valide las credenciales de cliente en el almacén de Edge, configura el elemento <ExternalAuthorization> como false dentro de la configuración de la política o omítelo 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 Edge no valide las credenciales del cliente, aún es necesario que Apigee Edge conozca y administre el client_id. Todos los access_tokens de Apigee Edge, ya sean generados por Apigee Edge o generados por un sistema externo y, luego, importados a Apigee Edge, deben estar asociados a una aplicación cliente (indicada por client_id). Por lo tanto, incluso en los casos en que la política OAuthV2/GenerateAccessToken en Apigee Edge no valide la coincidencia de client_id y client_secret, la política validará que client_id sea válido, presente y no revocado. Por lo tanto, como paso de configuración de requisitos previos, es posible que debas importar client_id a través de la API administrativa de Edge.

Flujo de políticas para OAuth de terceros en Apigee

Para usar tokens de sistemas OAuth de terceros en Apigee Edge, el flujo de generación de tokens de acceso debe seguir uno de los siguientes patrones.

Validación externa de credenciales de cliente

  1. ServiceCallout para verificar las credenciales del cliente entrante y adquirir un token externo.
  2. ExtractVariables o un paso de JavaScript para extraer el token generado de forma externa a partir de la respuesta.
  3. 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.
  4. 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 se configura la variable y el valor es verdadero, Apigee Edge no intenta validar las credenciales del cliente. Si la variable no está configurada o el valor no es verdadero, Apigee Edge intentará validar las credenciales del 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 Edge leerá esa variable para encontrar el token de acceso, el token de actualización o el código de autorización generados de forma externa. 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 de la política OAuthV2 le indica a Edge 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

La siguiente política de OAuthV2 genera un token de acceso de Apigee Edge, ya que Edge encuentra un valor de token en la variable de flujo external_access_token.

<OAuthV2 name="OAuth-v20-Store-External-Token">
    <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.