Usa OAuth2 para acceder a la API de Edge

Estás viendo la documentación de Apigee Edge.
Ir a la documentación de Apigee X. info

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 configurar primero 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 que podamos asegurarnos de que eres quien dices ser. Para autenticarte, requerimos que se envíe un token de acceso de OAuth2 con tu solicitud para acceder a la API.

Por ejemplo, si deseas obtener detalles sobre una organización en Edge, enviarías 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, necesitamos que nos envíes un token de acceso en esa solicitud. El token de acceso nos indica quién eres para que podamos asegurarnos de que tienes permiso para ver los detalles de la organización.

Afortunadamente, puedes obtener un token si envías tus credenciales al servicio OAuth2 de Edge. 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 realizas tu solicitud inicial a la API de Edge, sucede 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 OAuth2 de Edge 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 de forma silenciosa los tokens de acceso y actualización en ~/.sso-cli (el token de actualización no se escribe en stdout.) Si usas el servicio OAuth2 de Edge para obtener tokens, debes guardarlos para usarlos más adelante.

  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 las solicitudes posteriores, no es necesario que intercambies tus credenciales por un token. En su lugar, puedes incluir el token de acceso que ya tienes, siempre que aún 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, sucede 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, debes agregar el token de forma manual.
  2. La API de Edge ejecuta tu solicitud y, por lo general, muestra una respuesta con datos.

Flujo de OAuth2: Cuando vence tu token de acceso

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

Flujo de OAuth: Actualización del token de acceso
Figura 3: Flujo de OAuth: Actualización del token de acceso

Como se muestra en la Figura 3 , cuando vence tu token de acceso, sucede 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 como no 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 OAuth2 de Edge responde con un token de acceso nuevo.
  5. Envías una solicitud a la API de Edge con el token de acceso nuevo.
  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 conveniente alrededor de un comando estándar curl. 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 token en el servicio OAuth2 de Edge: Intercambia tus credenciales de Apigee por los tokens de acceso y actualización a través de una llamada a la API de Edge.

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

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

Como resultado, una vez que hayas realizado correctamente una llamada a la API con acurl o get_token, puedes seguir usando el par de tokens durante 30 días. Después 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 endpoint de 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.

El acceso a la API de Edge con acurl y curl se describe en las siguientes secciones.

Usa acurl

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

En las solicitudes posteriores, acurl usa 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 de la "ahamilton-eval" organización:

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, este ejemplo también muestra una segunda solicitud que obtiene una lista de políticas dentro del proxy de API "helloworld". La segunda solicitud usa la abreviatura "o" para "organizations" en la URL.

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

Para 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 actualización. Puedes obtenerlos con una utilidad como get_token o el servicio OAuth2 de Edge..

Después de guardar correctamente tu token de acceso, lo pasas en el Authorization encabezado de tus 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 durante 12 horas después de su emisión. Una vez que vence el token de acceso, el token de actualización se puede usar durante 30 días para emitir otro token de acceso sin necesidad de credenciales. Apigee recomienda solicitar un token de acceso nuevo solo después de que venza el token de actualización, en lugar de ingresar credenciales y realizar una solicitud nueva con cada llamada a la API.

Vencimiento del token

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

La forma en que actualizas tu token de acceso depende de la herramienta que uses:

  • acurl: No es necesario realizar ninguna acción. acurl actualiza automáticamente el token de acceso cuando envías una solicitud que contiene uno desactualizado.
  • get_token: Llama a get_token para actualizar el token de acceso.
  • Servicio OAuth2 de Edge: Envía una solicitud que incluya lo siguiente:
    • Token de actualización
    • Parámetro de formulario grant_type configurado como "refresh_token"

OAuth2 para usuarios de máquinas

Puedes usar las utilidades acurl y get_token para crear secuencias de comandos de acceso automático a las APIs 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 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 curl con 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 en una cadena vacía evitará que se le solicite un código de MFA a un usuario de máquina.