Usa OAuth2 para acceder a la API de Edge

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

Apigee Edge te permite realizar llamadas a la API de Edge que se autentican con tokens de OAuth2. La compatibilidad con OAuth2 está habilitada de forma predeterminada en Edge para las cuentas de Cloud. Si usas Edge para la nube privada, no puedes usar OAuth2 sin primero configurar SAML o LDAP.

Cómo funciona OAuth2 (con la API de Apigee Edge)

Las llamadas a la API de Apigee Edge requieren autenticación para asegurarnos de que eres quien dices ser. Para autenticarte, se te debe enviar un token de acceso de OAuth2 con tu solicitud de acceso a la API.

Por ejemplo, si deseas obtener detalles sobre una organización de Edge, debes enviar una solicitud a una URL como la siguiente:

https://api.enterprise.apigee.com/v1/organizations/ahamilton-eval

Pero no puedes enviar esa solicitud sin decirnos quién eres. De lo contrario, cualquiera podría ver los detalles de tu organización.

Aquí es donde entra en juego OAuth2: para autenticarte, también necesitamos que nos envíes un token de acceso en esa solicitud. El token de acceso nos indica quién eres para asegurarnos de que tienes permiso para ver los detalles de la organización.

Afortunadamente, para obtener un token, puedes enviar tus credenciales al servicio de Edge OAuth2. El servicio responde con tokens de acceso y actualización.

Flujo de OAuth2: La solicitud inicial

En la siguiente imagen, se muestra el flujo de OAuth2 cuando accedes a la API de Edge por primera vez:

Flujo de OAuth: Primera solicitud
Figura 1: Flujo de OAuth: Primera solicitud

Como se muestra en la Figura 1, cuando realices tu solicitud inicial a la API de Edge, ocurrirá lo siguiente:

  1. Solicitas un token de acceso. Puedes hacerlo con la API de Edge, acurl o get_token. Por ejemplo:
    get_token
    Enter username:
    ahamilton@apigee.com
    Enter the password for user 'ahamilton@apigee.com'
    [hidden input]
    Enter the six-digit code if 'ahamilton@apigee.com' is MFA enabled or press ENTER:
    123456
    .
  2. El servicio de Edge de OAuth2 responde con un token de acceso y lo imprime en stdout; por ejemplo:
    Dy42bGciOiJSUzI1NiJ9.eyJqdGkiOiJhM2YwNjA5ZC1lZTIxLTQ1YjAtOGQyMi04MTQ0MTYxNjNhNTMiLCJz
    AJpdGUiLCJhcHByb3ZhbHMubWUiLCJvYXV0aC5hcHByb3ZhbHMiXSwiY2xpZW50X2lkIjoiZWRnZWNsaSIsIm
    NjbGkiLCJhenAiOiJlZGdlY2xpIiwiZ3JhbnRfdHlwZSI6InBhc3N3b3JkIiwidXNlcl9pZCI6IjJkMWU3NDI
    GzQyMC1kYzgxLTQzMDQtOTM4ZS1hOGNmNmVlODZhNzkiLCJzY29wZSI6WyJzY2ltLm1lIiwib3BlbmlkIiwic
    ENC05MzhlLWE4Y2Y2ZWU4NmE3OSIsIm9yaWdpbiI6InVzZXJncmlkIiwidXNlcl9uYW1lIjoiZGFuZ2VyNDI0
    RI6ImUyNTM2NWQyIiwiaWF0IjoxNTI4OTE2NDA5LCJleHAiOjE1Mjg5MTgyMDksImlzcyI6Imh0dHBzOi8vbG
    420iLCJlbWFpbCI6ImRhbmdlcjQyNDJAeWFob28uY29tIiwiYXV0aF90aW1lIjoxNTI4OTE2NDA5LCJhbCI6M
    2lLmNvbSIsInppZCI6InVhYSIsImF1ZCI6WyJlZGdlY2xpIiwic2NpbSIsIm9wZW5pZCIsInBhc3N3b3JkIiw

    Las utilidades acurl y get_token guardan silenciosamente los tokens de acceso y de actualización en ~/.sso-cli (el token de actualización no se escribe en stdout). Si usas el servicio de Edge OAuth2 para obtener tokens, deberás guardarlos para usarlos más tarde.

  3. Envías una solicitud a la API de Edge con el token de acceso. acurl adjunta el token automáticamente; por ejemplo:
    acurl https://api.enterprise.apigee.com/v1/organizations/ahamilton-eval

    Si usas otro cliente HTTP, asegúrate de agregar el token de acceso. Por ejemplo:

    curl https://api.enterprise.apigee.com/v1/organizations/ahamilton-eval \
      -H "Authorization: Bearer ACCESS_TOKEN"
  4. La API de Edge ejecuta tu solicitud y, por lo general, muestra una respuesta con datos.

Flujo de OAuth2: Solicitudes posteriores

En solicitudes posteriores, no es necesario que intercambies tus credenciales por un token. En su lugar, puedes incluir el token de acceso que ya tengas, siempre que no haya vencido:

Flujo de OAuth: Solicitudes posteriores
Figura 2: Flujo de OAuth: Solicitudes posteriores

Como se muestra en la Figura 2, cuando ya tienes un token de acceso, ocurre lo siguiente:

  1. Envías una solicitud a la API de Edge con el token de acceso. acurl adjunta el token automáticamente. Si usas otras herramientas, deberás agregar el token manualmente.
  2. La API de Edge ejecuta tu solicitud y, por lo general, muestra una respuesta con datos.

Flujo de OAuth2: Cuándo vence tu token de acceso

Cuando un token de acceso venza (después de 12 horas), puedes usar el token de actualización para obtener un token de acceso nuevo:

Flujo de OAuth: Cómo actualizar el token de acceso
Figura 3: Flujo de OAuth: Actualización del token de acceso

Como se muestra en la figura 3, cuando venció el token de acceso, ocurre lo siguiente:

  1. Envías una solicitud a la API de Edge, pero tu token de acceso venció.
  2. La API de Edge rechaza tu solicitud porque no está autorizada.
  3. Envías un token de actualización al servicio OAuth2 de Edge. Si usas acurl, esto se hace automáticamente.
  4. El servicio de Edge de OAuth2 responde con un token de acceso nuevo.
  5. Envías una solicitud a la API de Edge con el nuevo token de acceso.
  6. La API de Edge ejecuta tu solicitud y, por lo general, muestra una respuesta con datos.

Obtén los tokens

Para obtener un token de acceso que puedas enviar a la API de Edge, puedes usar las siguientes utilidades de Apigee, además de una utilidad como curl:

  • Utilidad get_token: Intercambia tus credenciales de Apigee por tokens de acceso y actualización que puedes usar para llamar a la API de Edge.
  • Utilidad acurl: Proporciona un wrapper práctico alrededor de un comando curl estándar. Construye solicitudes HTTP a la API de Edge, obtiene tokens de acceso y actualización de get_token y pasa el token de acceso a la API de Edge.
  • Extremos de tokens en el servicio Edge OAuth2: Intercambia tus credenciales de Apigee por los tokens de acceso y actualiza mediante una llamada a la API de Edge.

Estas utilidades intercambian las credenciales de tu cuenta de Apigee (dirección de correo electrónico y contraseña) por tokens con la siguiente duración:

  • Los tokens de acceso vencen en 12 horas.
  • Los tokens de actualización vencen al cabo de 30 días.

Como resultado, una vez que hayas realizado correctamente una llamada a la API con acurl o get_token, podrás seguir usando el par de tokens durante 30 días. Luego del vencimiento, debes volver a ingresar tus credenciales y obtener tokens nuevos.

Accede a la API de Edge con OAuth2

Para acceder a la API de Edge, debes enviar una solicitud a un extremo de la API y, luego, incluir el token de acceso. Puedes hacerlo con cualquier cliente HTTP, incluida una utilidad de línea de comandos como curl, una IU basada en navegador, como Postman, o una utilidad de Apigee como acurl.

En las siguientes secciones, se describe el acceso a la API de Edge con acurl y curl.

Usa acurl

Para acceder a la API de Edge con acurl, la solicitud inicial debe incluir tus credenciales. El servicio de Edge OAuth2 responde con los tokens de acceso y actualización. acurl guarda los tokens de forma local.

En solicitudes posteriores, acurl usará los tokens guardados en ~/.sso-cli para que no tengas que volver a incluir tus credenciales hasta que venzan los tokens.

En el siguiente ejemplo, se muestra una solicitud acurl inicial que obtiene detalles sobre la organización “ahamilton-eval”:

acurl https://api.enterprise.apigee.com/v1/organizations/ahamilton-eval \
  -u ahamilton@apigee.com
Enter the password for user 'ahamilton@apigee.com'
[hidden input]
Enter the six-digit code (no spaces) if 'ahamilton@apigee.com' is MFA-enabled or press ENTER:
1a2b3c
{
  "createdAt" : 1491854501264,
  "createdBy" : "noreply_iops@apigee.com",
  "displayName" : "ahamilton",
  "environments" : [ "prod", "test" ],
  "lastModifiedAt" : 1491854501264,
  "lastModifiedBy" : "noreply_iops@apigee.com",
  "name" : "ahamilton",
  "properties" : {
    "property" : [ {
      "name" : "features.isSmbOrganization",
      "value" : "false"
    }, {
      "name" : "features.isCpsEnabled",
      "value" : "true"
    } ]
  },
  "type" : "trial"
}

acurl https://api.enterprise.apigee.com/v1/o/ahamilton-eval/apis/helloworld/revisions/1/policies

[ "SOAP-Message-Validation-1", "Spike-Arrest-1", "XML-to-JSON-1" ]

Además de obtener detalles sobre la organización, en este ejemplo también se muestra una segunda solicitud en la que se obtiene una lista de políticas dentro del proxy de la API “helloworld”. La segunda solicitud usa la abreviatura "o" para "organizaciones" en la URL.

Ten en cuenta que acurl pasa automáticamente el token de acceso en la segunda solicitud. No es necesario que pases las credenciales de usuario una vez que acurl almacene los tokens de OAuth2. Obtiene el token de ~/.sso-cli para las llamadas posteriores.

Si deseas obtener más información, consulta Usa acurl para acceder a la API de Edge.

Usa curl

Puedes usar curl para acceder a la API de Edge. Para ello, primero debes obtener los tokens de acceso y de actualización. Puedes obtenerlos con una utilidad como get_token o el servicio OAuth2 de Edge.

Una vez que hayas guardado correctamente el token de acceso, pásalo en el encabezado Authorization de las llamadas a la API de Edge, como se muestra en el siguiente ejemplo:

curl https://api.enterprise.apigee.com/v1/organizations/ahamilton-eval \
  -H "Authorization: Bearer ACCESS_TOKEN"

El token de acceso es válido por 12 horas después de su emisión. Una vez que venza el token de acceso, el token de actualización se puede usar durante 30 días para emitir otro token de acceso sin solicitar credenciales. Apigee recomienda solicitar un nuevo token de acceso solo después de que venza el token de referencia, en lugar de ingresar credenciales y realizar una nueva solicitud con cada llamada a la API.

Vencimiento del token

Una vez que venza el token de acceso, puedes usar el token de actualización para obtener uno nuevo sin tener que volver a enviar tus credenciales.

La forma de actualizar el token de acceso dependerá de la herramienta que uses:

  • acurl: No se requiere ninguna acción. acurl actualiza automáticamente el token de acceso cuando envías una solicitud que contiene una desactualizada.
  • get_token: Llama a get_token para actualizar el token de acceso.
  • Servicio Edge OAuth2: Envía una solicitud que incluya lo siguiente:
    • Token de actualización
    • El parámetro del formulario grant_type se estableció como "refresh_token".

OAuth2 para usuarios de máquinas

Puedes usar las utilidades acurl y get_token a fin de crear secuencias de comandos para el acceso automatizado a las API de Edge con autenticación OAuth2 para usuarios de máquinas. En el siguiente ejemplo, se muestra cómo usar get_token para solicitar un token de acceso y, luego, agregar el valor del token a una llamada a curl:

  USER=me@example.com
  PASS=not-that-secret
  TOKEN=$(get_token -u $USER:$PASS -m '')
  curl -H "Authorization: Bearer $TOKEN" 'https://api.enterprise.apigee.com/v1/organizations/...'

Como alternativa, puedes combinar la solicitud de token y la llamada a curl mediante la utilidad acurl. Por ejemplo:

  USER=me@example.com
  PASS=not-that-secret
  acurl -u $USER:$PASS -m '' 'https://api.enterprise.apigee.com/v1/organizations/...'
  

En ambos ejemplos, configurar el valor de -m como una string vacía evitará que se le solicite a un usuario de máquina un código MFA.