Obtener tokens de OAuth 2.0

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

Consulta la documentación de Apigee Edge.

En este documento se explica cómo obtener tokens de acceso y códigos de autorización de OAuth 2.0 con la API de Apigee. También te mostramos cómo crear políticas para cada tipo de autorización de OAuth 2.0 y cómo configurar endpoints de proxy para aceptar solicitudes de clientes.

Nota: Estos ejemplos muestran las configuraciones más básicas posibles. La política OAuthV2 incluye muchos elementos configurables opcionales que no se muestran en este tema. Para obtener más información sobre estos elementos, consulta la política OAuthV2.

Usar el tipo de concesión de código de autorización

En esta sección se explica cómo obtener un token de acceso mediante el flujo del tipo de concesión de código de autorización. La solicitud de token de este flujo requiere un código de autorización. Consulta Obtener un código de autorización. Consulta también ¿Qué son los tipos de concesión de OAuth 2.0?

Nota: La configuración de la política OAuthV2 de esta sección usa la GenerateAccessToken operación. Esta operación genera un formato de token de cadena opaca. También puedes generar tokens con formato JWT sustituyendo la operación GenerateJWTAccessToken. Consulta también Usar operaciones de tokens de OAuth JWT.

Solicitud de ejemplo

curl -i -H 'Content-Type: application/x-www-form-urlencoded' \
   -H 'Authorization: Basic c3FIOG9vSGV4VHo4QzAyg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ' \
   -X POST 'https://apitest.acme.com/oauth/token' \
   -d 'code=I9dMGHAN&grant_type=authorization_code&redirect_uri=http://example-callback.com' 

Parámetros obligatorios

De forma predeterminada, estos parámetros deben ser x-www-form-urlencoded y especificarse en el cuerpo de la solicitud (como se muestra en el ejemplo anterior). Sin embargo, es posible cambiar este valor predeterminado configurando los elementos <GrantType>, <Code> y <RedirectUri> en la política OAuthV2. Consulta la política de OAuthV2.

• grant_type debe tener el valor authorization_code.
• code: el código de autorización. Consulta Solicitar un código de autorización.
• redirect_uri debe proporcionar este parámetro si se ha incluido el parámetro redirect_uri en la solicitud de código de autorización. Si el parámetro redirect_uri no se ha incluido en la solicitud de código de autorización y no lo proporciona, esta política usará el valor de la URL de retrollamada proporcionada en la aplicación de desarrollador registrada.

Parámetros opcionales

• state: cadena que se enviará de vuelta con la respuesta. Se usa normalmente para evitar ataques de falsificación de solicitudes entre sitios.
• scope: te permite filtrar la lista de productos de API con los que se puede usar el token generado. Para obtener información detallada sobre los permisos, consulta el artículo Usar permisos OAuth2.

Autorización

Debes enviar el ID de cliente y el secreto de cliente como encabezado de autorización básica (codificado en Base64) o como parámetros de formulario client_id y client_secret. Estos valores se obtienen de una aplicación de desarrollador registrada. Consulta también Codificar credenciales de autenticación básicas.

Endpoint de ejemplo

A continuación, se muestra un ejemplo de configuración de endpoint para generar un token de acceso. Ejecutará la política GenerateAccessToken, que debe configurarse para admitir el tipo de concesión authorization_code.

...
       <Flow name="generate-access-token">
            <Description>Generate a token</Description>
            <Request>
                <Step>
                    <Name>GenerateAccessToken</Name>
                </Step>
            </Request>
            <Response/>
            <Condition>(proxy.pathsuffix MatchesPath "/token") and (request.verb = "POST")</Condition>
        </Flow>
...

Política de ejemplo

Esta es una política GenerateAccessToken básica configurada para aceptar el tipo de concesión authorization_code. Para obtener información sobre los elementos de configuración opcionales que puedes configurar con esta política, consulta la política OAuthV2.

<OAuthV2 name="GenerateAccessToken">
    <Operation>GenerateAccessToken</Operation>
    <ExpiresIn>1800000</ExpiresIn>
    <RefreshTokenExpiresIn>86400000</RefreshTokenExpiresIn>
    <SupportedGrantTypes>
      <GrantType>authorization_code</GrantType>
    </SupportedGrantTypes>
    <GenerateResponse enabled="true"/>
</OAuthV2>

Devoluciones

Si <GenerateResponse> está habilitado, la política devuelve una respuesta JSON que incluye el token de acceso, tal como se muestra a continuación. El tipo de concesión authorization_code crea un token de acceso y un token de actualización, por lo que una respuesta podría tener el siguiente aspecto:

{
    "issued_at": "1420262924658",
    "scope": "READ",
    "application_name": "ce1e94a2-9c3e-42fa-a2c6-1ee01815476b",
    "refresh_token_issued_at": "1420262924658",
    "status": "approved",
    "refresh_token_status": "approved",
    "api_product_list": "[PremiumWeatherAPI]",
    "expires_in": "1799", //--in seconds
    "developer.email": "[e-mail]",
    "organization_id": "0",
    "token_type": "BearerToken",
    "refresh_token": "fYACGW7OCPtCNDEnRSnqFlEgogboFPMm",
    "client_id": "5jUAdGv9pBouF0wOH5keAVI35GBtx3dT",
    "access_token": "2l4IQtZXbn5WBJdL6EF7uenOWRsi",
    "organization_name": "docs",
    "refresh_token_expires_in": "86399", //--in seconds
    "refresh_count": "0"
}

Nota: Sí, es algo inusual especificar los valores de vencimiento en milisegundos en la política, pero recibirlos en segundos en la carga útil de la respuesta. Somos conscientes.

Si se asigna el valor false a <GenerateResponse>, la política no devuelve ninguna respuesta. En su lugar, rellena el siguiente conjunto de variables de flujo con datos relativos a la concesión del token de acceso.

oauthv2accesstoken.{policy-name}.access_token
oauthv2accesstoken.{policy-name}.expires_in //--in seconds
oauthv2accesstoken.{policy-name}.refresh_token
oauthv2accesstoken.{policy-name}.refresh_token_expires_in //--in seconds
oauthv2accesstoken.{policy-name}.refresh_token_issued_at
oauthv2accesstoken.{policy-name}.refresh_token_status

Por ejemplo:

oauthv2accesstoken.GenerateAccessToken.access_token
oauthv2accesstoken.GenerateAccessToken.expires_in
oauthv2accesstoken.GenerateAccessToken.refresh_token
oauthv2accesstoken.GenerateAccessToken.refresh_token_expires_in
oauthv2accesstoken.GenerateAccessToken.refresh_token_issued_at
oauthv2accesstoken.GenerateAccessToken.refresh_token_status

Usar el tipo de autorización de credenciales de cliente

En esta sección se explica cómo obtener un token de acceso mediante el flujo del tipo de concesión de credenciales de cliente. Consulta también ¿Qué son los tipos de concesión de OAuth 2.0?

Nota: La configuración de la política OAuthV2 de esta sección usa la GenerateAccessToken operación. Esta operación genera un formato de token de cadena opaca. También puedes generar tokens con formato JWT sustituyendo la operación GenerateJWTAccessToken. Consulta también Usar operaciones de tokens de OAuth JWT.

Solicitud de ejemplo

curl -H "Content-Type: application/x-www-form-urlencoded" \
  -H "Authorization: Basic c3FIOG9vSGV4VHo4QzAyg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ" \
  -X POST "https://apitest.acme.com/oauth/token" \
  -d "grant_type=client_credentials"

Parámetros obligatorios

• grant_type debe tener el valor client_credentials.

  De forma predeterminada, el parámetro obligatorio grant_type debe ser x-www-form-urlencoded y especificarse en el cuerpo de la solicitud (como se muestra en el ejemplo anterior). Sin embargo, es posible cambiar este valor predeterminado configurando el elemento <GrantType> en la política OAuthV2. Por ejemplo, puede elegir transferir el parámetro en un parámetro de consulta. Para obtener más información, consulta la política OAuthV2.

Parámetros opcionales

• state: cadena que se enviará de vuelta con la respuesta. Se usa normalmente para evitar ataques de falsificación de solicitudes entre sitios.
• scope: te permite filtrar la lista de productos de API con los que se puede usar el token generado. Para obtener información detallada sobre los permisos, consulta el artículo Usar permisos OAuth2.

Autorización

Debes enviar el ID de cliente y el secreto de cliente como encabezado de autorización básica (codificado en Base64) o como parámetros de formulario client_id y client_secret. Estos valores se obtienen de la aplicación de desarrollador registrada asociada a la solicitud. Consulta también Codificar credenciales de autenticación básica.

Endpoint de ejemplo

A continuación, se muestra un ejemplo de configuración de endpoint para generar un token de acceso. Ejecutará la política GenerateAccessToken, que debe configurarse para admitir el tipo de autorización client_credentials.

...
       <Flow name="generate-access-token">
            <Request>
                <Step>
                    <Name>GenerateAccessToken</Name>
                </Step>
            </Request>
            <Response/>
            <Condition>(proxy.pathsuffix MatchesPath "/token") and (request.verb = "POST")</Condition>
        </Flow>
...

Política de ejemplo

Esta es una política GenerateAccessToken básica configurada para aceptar el tipo de concesión client_credentials. Para obtener información sobre los elementos de configuración opcionales que puedes configurar con esta política, consulta la política OAuthV2.

<OAuthV2 name="GenerateAccessToken">
    <Operation>GenerateAccessToken</Operation>
    <ExpiresIn>1800000</ExpiresIn> <!-- 30 minutes -->
    <SupportedGrantTypes>
      <GrantType>client_credentials</GrantType>
    </SupportedGrantTypes>
    <GenerateResponse enabled="true"/>
</OAuthV2>

Devoluciones

Si <GenerateResponse> está habilitado, la política devuelve una respuesta JSON. Ten en cuenta que, con el tipo de concesión client_credentials, no se admiten tokens de actualización. Solo se genera un token de acceso. Por ejemplo:

{
    "issued_at": "1420260525643",
    "application_name": "ce1e94a2-9c3e-42fa-a2c6-1ee01815476b",
    "scope": "READ",
    "status": "approved",
    "api_product_list": "[PremiumWeatherAPI]",
    "expires_in": "1799", //--in seconds
    "developer.email": "[e-mail]",
    "organization_id": "0",
    "token_type": "BearerToken",
    "client_id": "5jUAdGv9pBouF0wOH5keAVI35GBtx3dT",
    "access_token": "XkhU2DFnMGIVL2hvsRHLM00hRWav",
    "organization_name": "docs"
}

Si se asigna el valor false a <GenerateResponse>, la política no devuelve ninguna respuesta. En su lugar, rellena el siguiente conjunto de variables de flujo con datos relativos a la concesión del token de acceso.

oauthv2accesstoken.{policy-name}.access_token
oauthv2accesstoken.{policy-name}.expires_in //--in seconds

Por ejemplo:

oauthv2accesstoken.GenerateAccessToken.access_token
oauthv2accesstoken.GenerateAccessToken.expires_in     //--in seconds

Usar el tipo de autorización de contraseña

En esta sección se explica cómo obtener un token de acceso mediante el flujo del tipo de concesión de credenciales de contraseña del propietario del recurso (contraseña). Consulta también Implementar el tipo de autorización de contraseña. Consulta también ¿Qué son los tipos de concesión de OAuth 2.0?

Nota: La configuración de la política OAuthV2 de esta sección usa la GenerateAccessToken operación. Esta operación genera un formato de token de cadena opaca. También puedes generar tokens con formato JWT sustituyendo la operación GenerateJWTAccessToken. Consulta también Usar operaciones de tokens de OAuth JWT.

Solicitud de ejemplo

curl -v -k -H "Content-Type: application/x-www-form-urlencoded" \
  -H "Authorization: Basic c3FIOG9vSGV4VHo4QzAyg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ" \
  -X POST "https://apitest.acme.com/oauth/token" \
  -d "grant_type=password&username=a_username&password=a_password"

Parámetros obligatorios

De forma predeterminada, estos parámetros deben ser x-www-form-urlencoded y especificarse en el cuerpo de la solicitud (como se muestra en el ejemplo anterior). Sin embargo, es posible cambiar este valor predeterminado configurando los elementos <GrantType>, <Username> y <Password> en la política OAuthV2. Consulta la política de OAuthV2.

Las credenciales de usuario se suelen validar en un almacén de credenciales mediante una política de LDAP o JavaScript.

• grant_type debe tener el valor password.
• username: nombre de usuario del propietario del recurso.
• password: contraseña del propietario del recurso.

Parámetros opcionales

• state: cadena que se enviará de vuelta con la respuesta. Se usa normalmente para evitar ataques de falsificación de solicitudes entre sitios.
• scope: te permite filtrar la lista de productos de API con los que se puede usar el token generado. Para obtener información detallada sobre los permisos, consulta el artículo Usar permisos OAuth2.

Autorización

Debes enviar el ID de cliente y el secreto de cliente como encabezado de autorización básica (codificado en Base64) o como parámetros de formulario client_id y client_secret. Estos valores se obtienen de la aplicación de desarrollador registrada asociada a la solicitud. Consulta también Codificar credenciales de autenticación básica.

Endpoint de ejemplo

A continuación, se muestra un ejemplo de configuración de endpoint para generar un token de acceso. Ejecutará la política GenerateAccessToken, que debe configurarse para admitir el tipo de autorización de contraseña.

...
       <Flow name="generate-access-token">
            <Request>
                <Step>
                    <Name>GenerateAccessToken</Name>
                </Step>
            </Request>
            <Response/>
            <Condition>(proxy.pathsuffix MatchesPath "/token") and (request.verb = "POST")</Condition>
        </Flow>
...

Política de ejemplo

Esta es una política GenerateAccessToken básica configurada para aceptar el tipo de concesión de contraseña. Para obtener información sobre los elementos de configuración opcionales que puedes configurar con esta política, consulta la política OAuthV2.

<OAuthV2 name="GenerateAccessToken">
    <Operation>GenerateAccessToken</Operation>
    <ExpiresIn>1800000</ExpiresIn> <!-- 30 minutes -->
    <RefreshTokenExpiresIn>28800000</RefreshTokenExpiresIn> <!-- 8 hours -->
    <SupportedGrantTypes>
      <GrantType>password</GrantType>
    </SupportedGrantTypes>
    <GenerateResponse enabled="true"/>
</OAuthV2>

Devoluciones

Si <GenerateResponse> está habilitado, la política devuelve una respuesta JSON. Ten en cuenta que, con el tipo de concesión de contraseña, se generan un token de acceso y un token de actualización. Por ejemplo:

{
    "issued_at": "1420258685042",
    "scope": "READ",
    "application_name": "ce1e94a2-9c3e-42fa-a2c6-1ee01815476b",
    "refresh_token_issued_at": "1420258685042",
    "status": "approved",
    "refresh_token_status": "approved",
    "api_product_list": "[PremiumWeatherAPI]",
    "expires_in": "1799", //--in seconds
    "developer.email": "[e-mail]",
    "organization_id": "0",
    "token_type": "BearerToken",
    "refresh_token": "IFl7jlijYuexu6XVSSjLMJq8SVXGOAAq",
    "client_id": "5jUAdGv9pBouF0wOH5keAVI35GBtx3dT",
    "access_token": "I6daIgMSiUgYX1K2qgQWPi37ztS6",
    "organization_name": "docs",
    "refresh_token_expires_in": "28799", //--in seconds
    "refresh_count": "0"
}

Si se asigna el valor false a <GenerateResponse>, la política no devuelve ninguna respuesta. En su lugar, rellena el siguiente conjunto de variables de flujo con datos relativos a la concesión del token de acceso.

oauthv2accesstoken.{policy-name}.access_token
oauthv2accesstoken.{policy-name}.expires_in   //--in seconds
oauthv2accesstoken.{policy-name}.refresh_token
oauthv2accesstoken.{policy-name}.refresh_token_expires_in  //--in seconds
oauthv2accesstoken.{policy-name}.refresh_token_issued_at
oauthv2accesstoken.{policy-name}.refresh_token_status

Por ejemplo:

oauthv2accesstoken.GenerateAccessToken.access_token
oauthv2accesstoken.GenerateAccessToken.expires_in
oauthv2accesstoken.GenerateAccessToken.refresh_token
oauthv2accesstoken.GenerateAccessToken.refresh_token_expires_in
oauthv2accesstoken.GenerateAccessToken.refresh_token_issued_at
oauthv2accesstoken.GenerateAccessToken.refresh_token_status

Usar el tipo de autorización implícita

En esta sección se explica cómo obtener un token de acceso mediante el flujo del tipo de concesión implícita. Consulta también ¿Qué son los tipos de concesión de OAuth 2.0?

Nota: La configuración de la política OAuthV2 de esta sección usa la GenerateAccessTokenImplicitGrant operación. Esta operación genera un formato de token de cadena opaca. También puedes generar tokens con formato JWT sustituyendo la operación GenerateJWTAccessTokenImplicitGrant. Consulta también Usar operaciones de tokens de OAuth JWT.

Solicitud de ejemplo

$ curl -X POST -H 'Content-Type: application/x-www-form-urlencoded' \
  'https://apitest.acme.com/oauth/implicit?response_type=token&client_id=c3FIOG9vSGV4VHo4QzAyg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ&redirect_uri=http://callback-example.com'

Parámetros obligatorios

De forma predeterminada, estos parámetros deben ser parámetros de consulta (como se muestra en el ejemplo anterior). Sin embargo, es posible cambiar este valor predeterminado configurando los elementos <ResponseType>, <ClientId> y <RedirectUri> en la política OAuthV2 que está asociada a este endpoint /token. Para obtener más información, consulta la política OAuthV2.

Las credenciales de usuario se suelen validar en un almacén de credenciales mediante una llamada de servicio LDAP o una política de JavaScript.

• response_type debe tener el valor token.
• client_id el ID de cliente de una aplicación de desarrollador registrada.
• redirect_uri este parámetro es obligatorio si no se ha proporcionado un URI de retrollamada al registrar la aplicación del desarrollador del cliente. Si se proporcionó una URL de retrollamada al registrar el cliente, se comparará con este valor y debe coincidir exactamente.

Parámetros opcionales

• state: cadena que se enviará de vuelta con la respuesta. Se usa normalmente para evitar ataques de falsificación de solicitudes entre sitios.
• scope: te permite filtrar la lista de productos de API con los que se puede usar el token generado. Para obtener información detallada sobre los permisos, consulta el artículo Usar permisos OAuth2.

Autorización

No requiere el encabezado Authorization, pero sí debe transferir un ID de cliente como parámetro de solicitud.

Endpoint de ejemplo

A continuación, se muestra un ejemplo de configuración de endpoint para generar un token de acceso. Ejecutará la política GenerateAccessTokenImplicitGrant.

...
       <Flow name="generate-access-token-implicit">
            <Request>
                <Step>
                    <Name>GenerateAccessTokenImplicitGrant</Name>
                </Step>
            </Request>
            <Response/>
            <Condition>(proxy.pathsuffix MatchesPath "/implicit") and (request.verb = "POST")</Condition>
        </Flow>
...

Política de ejemplo

Se trata de una política básica de GenerateAccessTokenImplicitGrant que procesa las solicitudes de tokens del flujo de tipo de concesión implícita. Para obtener información sobre los elementos de configuración opcionales que puedes configurar con esta política, consulta la política OAuthV2.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<OAuthV2 name="GenerateAccessTokenImplicit">
    <DisplayName>GenerateAccessTokenImplicit</DisplayName>
    <Operation>GenerateAccessTokenImplicitGrant</Operation>
    <GenerateResponse enabled="true"/>
</OAuthV2>

Devoluciones

Si <GenerateResponse> está habilitado, la política devuelve una redirección de ubicación 302 en el encabezado de respuesta. La redirección apunta a la URL especificada en el parámetro redirect_uri y se le añade el token de acceso y el tiempo de caducidad del token. Ten en cuenta que el tipo de concesión implícito no admite tokens de actualización. Por ejemplo:

https://callback-example.com#expires_in=1799&access_token=In4dKm4ueoGZRbIYJhC9yZCmTFw5

Si se asigna el valor false a <GenerateResponse>, la política no devuelve ninguna respuesta. En su lugar, rellena el siguiente conjunto de variables de flujo con datos relativos a la concesión del token de acceso.

oauthv2accesstoken.{policy-name}.access_token
oauthv2accesstoken.{policy-name}.expires_in  //--in seconds

Por ejemplo:

oauthv2accesstoken.GenerateAccessToken.access_token
oauthv2accesstoken.GenerateAccessToken.expires_in   //--in seconds

Obtener un código de autorización

En el flujo del tipo de concesión de código de autorización, se necesita un código de autorización para obtener un token de acceso. Consulta Usar el tipo de concesión de código de autorización. Consulta también ¿Qué son los tipos de concesión de OAuth 2.0?

Nota: El flujo de código de autorización se produce entre un servicio de autenticación de usuario de terceros y Apigee. El objetivo del flujo del tipo de concesión de código de autorización es que la aplicación cliente nunca vea las credenciales del usuario para el servidor de recursos. Para obtener información detallada sobre este flujo, consulta Implementar el tipo de autorización de código de autorización.

Solicitud de ejemplo

curl -X POST -H "Content-Type: application/x-www-form-urlencoded" \
  "https://apitest.acme.com/oauth/authorize?response_type=code&client_id=c3FIOG9vSGV4VHo4QzAyg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ&redirect_uri=http://my-callback.com"

Parámetros obligatorios

De forma predeterminada, estos parámetros deben ser parámetros de consulta (como se muestra en el ejemplo anterior). Sin embargo, se puede cambiar este valor predeterminado configurando los elementos <ResponseType>, <ClientId> y <RedirectUri> en la política OAuthV2. Para obtener más información, consulta la política OAuthV2.

• redirect_uri si se especifica una URI de retrollamada completa (no parcial) en la aplicación cliente registrada, este parámetro es opcional. De lo contrario, es obligatorio. La retrollamada es la URL a la que Apigee envía el código de autorización recién generado. Consulta también Registrar aplicaciones y gestionar claves de API.
• response_type debe tener el valor code.
• client_id el ID de cliente de una aplicación de desarrollador registrada.

Parámetros opcionales

• redirect_uri si se especifica una URI de retrollamada completa (no parcial) en la aplicación cliente registrada, este parámetro es opcional. De lo contrario, es obligatorio. La retrollamada es la URL a la que Apigee envía el código de autorización recién generado. Consulta también Registrar aplicaciones y gestionar claves de API.
• state: cadena que se enviará de vuelta con la respuesta. Se usa normalmente para evitar ataques de falsificación de solicitudes entre sitios.
• scope: te permite filtrar la lista de productos de API con los que se puede usar el token generado. Para obtener información detallada sobre los permisos, consulta el artículo Usar permisos OAuth2.

Autorización

No requiere el encabezado Authorization, pero en la solicitud se debe proporcionar el ID de cliente de la aplicación cliente registrada.

Política de ejemplo

Esta es una política básica de GenerateAuthorizationCode. Para ver más opciones de configuración, consulta la política OAuthV2:

<OAuthV2 name="GenerateAuthorizationCode">
    <Operation>GenerateAuthorizationCode</Operation>
    <GenerateResponse enabled="true"/>
</OAuthV2>

Devoluciones

Si <GenerateResponse> está habilitado, la política devuelve el parámetro de consulta ?code a la ubicación redirect_uri (URI de retrollamada) con el código de autorización adjunto. Se envía a través de una redirección 302 del navegador con la URL en el encabezado Location de la respuesta. Por ejemplo: ?code=123456.

Si <GenerateResponse> tiene el valor false, la política no devuelve ninguna respuesta. En su lugar, rellena el siguiente conjunto de variables de flujo con datos relativos al código de autorización.

oauthv2authcode.{policy-name}.code
oauthv2authcode.{policy-name}.scope
oauthv2authcode.{policy-name}.redirect_uri
oauthv2authcode.{policy-name}.client_id

Por ejemplo:

oauthv2authcode.GenerateAuthorizationCode.code
oauthv2authcode.GenerateAuthorizationCode.scope
oauthv2authcode.GenerateAuthorizationCode.redirect_uri
oauthv2authcode.GenerateAuthorizationCode.client_id

Nota: También puedes definir atributos personalizados en la política OAuthV2. Los atributos personalizados se devolverán con el mismo formato que las demás variables: oauthv2.{policy_name}.{attribute_name}. Cuando generas un token de acceso a partir del código de autorización, el token de acceso hereda las variables personalizadas definidas en el código de autorización. Consulta también la política de OAuth V2.

Actualizar un token de acceso

Un token de actualización es una credencial que se usa para obtener un token de acceso, normalmente después de que el token de acceso haya caducado o deje de ser válido. Cuando recibas un token de acceso, se devolverá un token de actualización en la respuesta.

Nota: La configuración de la política OAuthV2 de esta sección usa la RefreshAccessToken operación. Esta operación actualiza un formato de token de cadena opaca. También puedes actualizar los tokens con formato JWT sustituyendo la operación RefreshJWTAccessToken. Consulta también Usar operaciones de tokens de OAuth JWT.

Nota: Los atributos de un token de acceso no se pueden añadir, eliminar ni modificar durante la operación RefreshAccessToken. Los valores del elemento no se procesan en la operación RefreshAccessToken. Usa la política SetOAuthV2Info para actualizar los atributos.

Solicitud de ejemplo

Para obtener información sobre cómo codificar el encabezado de autenticación básica en la siguiente llamada, consulta Codificación de credenciales de autenticación básica.

$ curl -X POST \
  -H "Content-type: application/x-www-form-urlencoded" \
  -H "Authorization: Basic c3FIOG9vSGV4VHo4QzAyg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ" \
  https://apitest.acme.com/oauth/refresh \
  -d "grant_type=refresh_token&refresh_token=yVSL38WpuN3Kzn1UTMoE6AQ4ANZM"

Parámetros obligatorios

De forma predeterminada, la política busca estos parámetros x-www-form-urlencoded especificados en el cuerpo de la solicitud, como se muestra en el ejemplo anterior. Para configurar una ubicación alternativa para estas entradas, puedes usar los elementos <GrantType> y <RefreshToken> en la política OAuthV2. Para obtener más información, consulta la política OAuthV2.

• grant_type debe tener el valor refresh_token.
• refresh_token el token de actualización asociado al token de acceso que quieres renovar.

Parámetros opcionales

• state: cadena que se enviará de vuelta con la respuesta. Se usa normalmente para evitar ataques de falsificación de solicitudes entre sitios.
• scope: te permite filtrar la lista de productos de API con los que se puede usar el token generado. Para obtener información detallada sobre los permisos, consulta el artículo Usar permisos OAuth2.

Autorización

No requiere el encabezado Authorization, pero en la solicitud se debe proporcionar el ID de cliente de la aplicación cliente registrada.

Cuando se actualiza un token de acceso, no se vuelve a autenticar al usuario.

A continuación, se muestra un ejemplo de configuración de endpoint para generar un token de acceso mediante un token de actualización. Ejecutará la política RefreshAccessToken.

 ...
       <Flow name="generate-refresh-token">
            <Request>
                <Step>
                    <Name>RefreshAccessToken</Name>
                </Step>
            </Request>
            <Response/>
            <Condition>(proxy.pathsuffix MatchesPath "/refresh") and (request.verb = "POST")</Condition>
       </Flow>
...

Política de ejemplo

Se trata de una política RefreshAccessToken básica configurada para aceptar el tipo de concesión refresh_token. Para obtener información sobre los elementos de configuración opcionales que puedes configurar con esta política, consulta la política OAuthV2.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<OAuthV2 name="RefreshAccessToken">
    <Operation>RefreshAccessToken</Operation>
    <GenerateResponse enabled="true"/>
    <ExpiresIn>1800000</ExpiresIn> <!-- 30 minutes -->
    <RefreshTokenExpiresIn>28800000</RefreshTokenExpiresIn> <!-- 8 hours -->
</OAuthV2>

Devoluciones

Si <GenerateResponse> está habilitado, la política devuelve una respuesta JSON que contiene el nuevo token de acceso. El tipo de concesión refresh_token admite la creación de tokens de acceso y de actualización. Por ejemplo:

{
    "issued_at": "1420301470489",
    "application_name": "ce1e94a2-9c3e-42fa-a2c6-1ee01815476b",
    "scope": "READ",
    "refresh_token_issued_at": "1420301470489",
    "status": "approved",
    "refresh_token_status": "approved",
    "api_product_list": "[PremiumWeatherAPI]",
    "expires_in": "1799", //--in seconds
    "developer.email": "[e-mail]",
    "token_type": "BearerToken",
    "refresh_token": "8fKDHLryAD9KFBsrpixlq3qPJnG2fdZ5",
    "client_id": "5jUAdGv9pBouF0wOH5keAVI35GBtx3dT",
    "access_token": "jmZ2Hqv3iNsABUtAAsfWR3QGNctw",
    "organization_name": "docs",
    "refresh_token_expires_in": "28799", //--in seconds
    "refresh_count": "2"
}

Nota: La fecha de vencimiento del token de acceso y del token de actualización que se indica en la respuesta es 1 segundo inferior a la especificada en la configuración de la política. Esto se debe al tiempo de tránsito y a un margen de seguridad. Sí, es un poco raro especificar los valores de vencimiento en milisegundos en la política, pero recibirlos en segundos en la carga útil de la respuesta. Somos conscientes.

Debes saber que, después de generar un nuevo token de actualización, el original deja de ser válido.

La respuesta anterior es la que obtienes si <GenerateResponse> se establece en true. Si se asigna el valor "false" a <GenerateResponse>, la política no devuelve ninguna respuesta. En su lugar, rellena el siguiente conjunto de variables de contexto (flujo) con datos relativos a la concesión del token de acceso.

oauthv2accesstoken.{policy-name}.access_token
oauthv2accesstoken.{policy-name}.expires_in   //--in seconds
oauthv2accesstoken.{policy-name}.refresh_token
oauthv2accesstoken.{policy-name}.refresh_token_expires_in  //--in seconds
oauthv2accesstoken.{policy-name}.refresh_token_issued_at
oauthv2accesstoken.{policy-name}.refresh_token_status

Por ejemplo:

oauthv2accesstoken.RefreshAccessToken.access_token
oauthv2accesstoken.RefreshAccessToken.expires_in
oauthv2accesstoken.RefreshAccessToken.refresh_token
oauthv2accesstoken.RefreshAccessToken.refresh_token_expires_in
oauthv2accesstoken.RefreshAccessToken.refresh_token_issued_at
oauthv2accesstoken.RefreshAccessToken.refresh_token_status

Codificación de las credenciales de autenticación básica

Cuando haces una llamada a la API para solicitar un token o un código de autorización, es recomendable y es una práctica recomendada por la especificación de OAuth 2.0 pasar los valores client_id y client_secret como un encabezado de autorización HTTP-Basic, tal como se describe en IETF RFC 2617. Para ello, debe codificar en Base64 el resultado de unir los dos valores con dos puntos entre ellos.

En pseudocódigo:

result = Base64Encode(concat('ns4fQc14Zg4hKFCNaSzArVuwszX95X', ':', 'ZIjFyTsNgQNyxI'))

Donde ns4fQc14Zg4hKFCNaSzArVuwszX95X es el client_id y ZIjFyTsNgQNyxI es el secreto de cliente.

Ejemplos

Este comando de ejemplo funciona en Linux y macOS:

export CREDENTIALS=$(echo -n 'ns4fQc14Zg4hKFCNaSzArVuwszX95X:ZIjFyTsNgQNyxI' | base64)

A continuación, puedes hacer la solicitud de token de la siguiente manera:

$ curl -i -H "Content-Type: application/x-www-form-urlencoded" \
  -H "Authorization: Basic $CREDENTIALS" \
  -X POST "https://apitest.acme.com/oauth/token" \
  -d "grant_type=client_credentials"

Crear hashes de tokens en la base de datos

Apigee cifra con hash todos los tokens de acceso y de actualización de OAuth para protegerlos en caso de que se produzca una brecha de seguridad en la base de datos. Utilizas tokens sin cifrar en las llamadas a la API y Apigee los valida comparándolos con las versiones cifradas de la base de datos.

Temas relacionados

• Implementar el tipo de autorización de credenciales de cliente
• Implementar el tipo de concesión de código de autorización
• Curso online sobre seguridad de APIs (incluye OAuth)
• Política OAuthV2: incluye muchos ejemplos que muestran cómo hacer solicitudes al servidor de autorización y cómo configurar la política OAuthV2.