OAuth

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

OAuth se convirtió en el protocolo de autorización líder para APIs. La versión de OAuth que se aborda en detalle en este tema se define en la especificación de OAuth 2.0.

OAuth es un protocolo que permite a los usuarios finales de la app autorizar a las apps para que actúen en su nombre. Para ello, las apps obtienen tokens de acceso de proveedores de API. El proveedor de la API autentica las credenciales del usuario final de la aplicación, se asegura de que el usuario haya autorizado la aplicación y, luego, emite un token de acceso a la aplicación. Cuando la aplicación consume una API protegida, Apigee Edge verifica el token de acceso para garantizar que sea válido y que no haya vencido. Como proveedor de API, debes exponer extremos que permitan que las apps obtengan tokens de acceso.

Para facilitarte comenzar a usar OAuth, Apigee Edge te permite configurar y aplicar OAuth mediante políticas, sin necesidad de escribir ningún código. En este tema, aprenderás cómo proteger tus APIs, cómo obtener tokens de acceso y cómo usarlos para acceder a APIs protegidas.

La configuración de OAuth predeterminada para tu organización

Para mayor comodidad, todas las organizaciones de Apigee Edge vienen preconfiguradas con un conjunto de extremos de OAuth 2.0 que implementan el tipo de otorgamiento de credenciales de cliente. El tipo de otorgamiento de credenciales de cliente define un procedimiento para emitir tokens de acceso a cambio de credenciales de apps. Estas credenciales de app son simplemente el par clave y secreto del consumidor que Apigee Edge emite para cada app que está registrada en una organización. “Credenciales de cliente” hace referencia a la clave del consumidor y al par secreto.

Si deseas obtener más información sobre cómo emitir credenciales para las apps que usan los servicios para desarrolladores de Edge, consulta Registra apps y administra claves.

Por este motivo, es relativamente sencillo "aumentar" tu esquema de seguridad de API desde la validación de claves de API hasta las credenciales de cliente de OAuth. Ambos esquemas usan la misma clave y el mismo secreto de consumidor para validar la app cliente. La diferencia es que las credenciales de cliente proporcionan una capa adicional de control, ya que puedes revocar fácilmente un token de acceso cuando sea necesario, sin necesidad de revocar la clave de consumidor de la app. Para trabajar con los extremos de OAuth predeterminados, puedes usar cualquier clave y secreto de consumidor generados para la app de tu organización a fin de recuperar tokens de acceso desde el extremo del token. (Incluso, puedes habilitar las credenciales de cliente para las apps que ya tienen claves y secretos del consumidor).

Puedes encontrar la especificación completa para el otorgamiento de credenciales de cliente en la especificación de OAuth 2.0.

Protege tu API con una política

Antes de poder usar tokens de acceso, debes configurar tus APIs para validar los tokens de acceso de OAuth en el entorno de ejecución. Para ello, configura un proxy de API para validate los tokens de acceso. Esto significa que cada vez que una app realiza una solicitud para consumir una de tus APIs, debe presentar un token de acceso válido junto con la solicitud a la API. Apigee Edge maneja la complejidad detrás de la generación, el almacenamiento y la validación de los tokens de acceso que se presentan.

Puedes agregar fácilmente la verificación de OAuth a una API cuando creas un proxy de API nuevo. Cuando creas un nuevo proxy de API, puedes Agregar funciones. Como se muestra a continuación, puedes agregar la verificación de tokens de acceso de OAuth 2.0. Para ello, selecciona el botón de selección junto a Proteger con tokens de acceso de OAuth v2.0. Si seleccionas esta opción, se adjuntarán dos políticas al proxy de API recién creado: una para verificar los tokens de acceso y otra para quitarlo después de que se haya verificado.

Además, cuando seleccionas la opción Secure with OAuth v2.0 Access Tokens, se puede seleccionar la casilla de verificación Publish API Product automáticamente. Marca esta opción si deseas generar un producto automáticamente cuando compiles el nuevo proxy de API. El producto generado automáticamente se creará con una asociación al proxy de API nuevo. Si ya tienes un producto con el que deseas asociar esta API nueva, asegúrate de desmarcar esta casilla de verificación para no crear un producto innecesario. Para obtener información sobre los productos, consulta ¿Qué es un producto de API?

Si necesitas habilitar la verificación de token de acceso para el proxy de API que ya existe, lo único que debes hacer es adjuntar una política de tipo OAuthV2 a la API que quieres proteger. Las políticas de OAuthV2 funcionan especificando una operación. Si deseas validar los tokens de acceso, especifica la operación llamada VerifyAccessToken. (Otros tipos de operaciones compatibles con la política de OAuthV2 son GenerateAccessToken y GenerateRefreshToken. Aprenderás sobre esas operaciones cuando configures extremos de OAuth).

Política VerifyOAuthTokens de tipo OAuthV2

Una política de ejemplo para validar tokens de acceso es similar a la siguiente. (Las opciones de configuración se explican en la siguiente tabla).

<OAuthV2 name="VerifyOAuthTokens"> 
  <Operation>VerifyAccessToken</Operation> 
</OAuthV2>

Configuración de la política

Nombre Descripción Predeterminada ¿Obligatorio?
OAuthV2 El tipo de política
name El nombre de la política, a la que se hace referencia en la configuración del extremo del proxy de la API. No disponible
Operation La operación que ejecutará la política OAuthV2. Si especificas VerifyAccessToken, configurarás la política para verificar las solicitudes de tokens de acceso y verificar que el token de acceso sea válido, no haya vencido y esté aprobado para consumir el recurso de API (URI) solicitado. (Para realizar esta verificación, la política lee el producto de API que la app puede consumir). No disponible

Para crear esta política en la IU de administración, navega a APIs > Proxies de API.

En la lista de proxies de API, selecciona weatherapi.

En Overview de la weatherapi, selecciona la vista Develop.

En el menú desplegable, selecciona Política nueva > OAuth v2.0.

Después de seleccionar la política de OAuth v2.0, aparecerá el menú de configuración Política nueva.

Asigna un nombre descriptivo a la política y asegúrate de seleccionar Attach Policy, Flow PreFlow y Request como configuración de la política adjunta.

Selecciona Add; la política se creará y se adjuntará al PreFlow de la solicitud de weatherapi.

Después de agregar la política, la configuración de la solicitud de PreFlow que se muestra a continuación en el panel Designer.

Si trabajas de forma local en un editor de texto o IDE, debes adjuntar la política al PreFlow de la solicitud del proxy de API que deseas proteger:

<PreFlow>
  <Request>
    <Step><Name>VerifyOAuthTokens</Name></Step>
  </Request>
</PreFlow>

Si adjuntas la política al PreFlow de la solicitud, te asegurarás de que la política siempre se aplique en todos los mensajes de solicitud.

Protegiste una API con credenciales de cliente de OAuth 2.0. El siguiente paso es aprender a obtener un token de acceso y usarlo para acceder a la API segura.

Usa un token de acceso para acceder a un recurso protegido

Ahora que weatherapi está protegida con OAuth 2.0, las apps deben presentar tokens de acceso para consumir la API. Para acceder a un recurso protegido, la app presenta un token de acceso en la solicitud como un encabezado HTTP"Authorization" de la siguiente manera:

$ curl -H "Authorization: Bearer ylSkZIjbdWybfs4fUQe9BqP0LH5Z" http://{org_name}-test.apigee.net/weather/forecastrss?w=12797282

Debido a que la API tiene una política OAuthV2 adjunta, Apigee Edge verificará que el token de acceso presentado sea válido y, luego, otorgará acceso a la API y mostrará el informe del clima a la app que realizó la solicitud.

Pero ¿cómo obtienen tokens de acceso las apps? Abordaremos esto en la próxima sección.

Cómo intercambiar credenciales de cliente por un token de acceso

Para obtener tokens de acceso, las apps presentan sus pares clave-secreto del consumidor en el extremo del token. El extremo del token se configura en el proxy de API llamado oauth. Por lo tanto, las apps deben llamar a la API expuesta por el proxy de la API oauth para obtener un token de acceso. Después de que la app tiene un token de acceso, puede llamar a la weatherapi repetidas veces, hasta que el token de acceso venza o se revoque el token de acceso.

Ahora debes cambiar de marcha para pensar en ti como desarrollador de apps. Como quieres llamar a la weatherapi, debes obtener un token de acceso para tu app. Lo primero que debes hacer es obtener una clave de consumidor y un par secreto (también conocida como clave de API o clave de app).

Puedes obtener una clave y un secreto de consumidor si registras una app en tu organización en Apigee Edge.

Puedes ver todas las apps de tu organización en la IU de administración de Apigee Edge.

Se mostrará la lista de apps registradas en tu organización.

(Si no se muestra ninguna app, puedes obtener información para registrar una app en el tema Registra apps y administra claves de API).

Selecciona una app de la lista para ver su perfil detallado.

En la vista de detalles de la app que seleccionaste, anota los campos Consumer Key y Consumer Secret. Estos dos valores son las credenciales de cliente que utilizarás para obtener un token de acceso de OAuth.

$ curl https://api.enterprise.apigee.com/v1/o/{org_name}/apps \
-u myname:mypass 

Esta llamada muestra una lista de apps por ID de app.

[ "da496fae-2a04-4a5c-b2d0-709278a6f9db", "50e3e831-175b-4a05-8fb6-05a54701af6e" ]

Puedes recuperar el perfil de una app si realizas una llamada GET simple en el ID de la app:

$ curl https://api.enterprise.apigee.com/v1/o/{org_name}/apps/{app_id} \
-u myname:mypass 

Por ejemplo:

$ curl https://api.enterprise.apigee.com/v1/o/{org_name}/apps/da496fae-2a04-4a5c-b2d0-709278a6f9db \
-u myname:mypass 

La llamada a la API muestra el perfil de la app que especificaste. Por ejemplo, un perfil de app para weatherapp tiene la siguiente representación JSON:

{
  "accessType" : "read",
  "apiProducts" : [ ],
  "appFamily" : "default",
  "appId" : "da496fae-2a04-4a5c-b2d0-709278a6f9db",
  "attributes" : [ ],
  "callbackUrl" : "http://weatherapp.com",
  "createdAt" : 1380290158713,
  "createdBy" : "noreply_admin@apigee.com",
  "credentials" : [ {
    "apiProducts" : [ {
      "apiproduct" : "PremiumWeatherAPI",
      "status" : "approved"
    } ],
    "attributes" : [ ],
    "consumerKey" : "bBGAQrXgivA9lKu7NMPyoYpVKNhGar6K",
    "consumerSecret" : "hAr4Gn0gA9vAyvI4",
    "expiresAt" : -1,
    "issuedAt" : 1380290161417,
    "scopes" : [ ],
    "status" : "approved"
  } ],
  "developerId" : "5w95xGkpnjzJDBT4",
  "lastModifiedAt" : 1380290158713,
  "lastModifiedBy" : "noreply_admin@apigee.com",
  "name" : "weatherapp",
  "scopes" : [ ],
  "status" : "approved"
}

Anota los valores de consumerKey y consumerSecret. Usa estas credenciales para obtener un token de acceso presentándolas como credenciales de autenticación básica en una solicitud HTTP, como se muestra a continuación. El tipo de otorgamiento se presenta como un parámetro de consulta a la solicitud. (Asegúrate de cambiar el valor de la variable {org_name} para reflejar el nombre de tu organización en Apigee Edge).

Crea una solicitud para obtener un token de acceso

En la siguiente solicitud, sustituye el valor de tu consumerKey por client_id. Sustituye el valor del consumerSecret asociado por client_secret.

$ curl https://{org_name}-test.apigee.net/oauth/client_credential/accesstoken?grant_type=client_credentials -X POST -d 'client_id=bBGAQrXgivA9lKu7NMPyoYpVKNhGar6K&client_secret=hAr4Gn0gA9vAyvI4'

Los servicios de la API verifican la clave y el secreto del consumidor y, luego, generan una respuesta que contiene el token de acceso para esta app:

{
  "issued_at" : "1380892555397",
  "application_name" : "957aa73f-25c2-4ead-8021-adc01f0d2c6b",
  "scope" : "",
  "status" : "approved",
  "api_product_list" : "[oauth-test]",
  "expires_in" : "3599",
  "developer.email" : "tesla@weathersample.com",
  "organization_id" : "0",
  "client_id" : "bBGAQrXgivA9lKu7NMPyoYpVKNhGar6K",
  "access_token" : "ylSkZIjbdWybfs4fUQe9BqP0LH5Z",
  "organization_name" : "rqa",
  "refresh_token_expires_in" : "0",
  "refresh_count" : "0"
}

Observa el valor access_token en la respuesta anterior. Este es el token de acceso que usará la app para obtener acceso durante el tiempo de ejecución a los recursos protegidos. El token de acceso para esta app es ylSkZIjbdWybfs4fUQe9BqP0LH5Z.

Ahora tienes un token de acceso válido, ylSkZIjbdWybfs4fUQe9BqP0LH5Z, que se puede usar para acceder a las APIs protegidas.

Trabaja con la configuración predeterminada de OAuth

Cada organización (incluso una organización de prueba gratuita) en Apigee Edge se aprovisiona con un extremo de token de OAuth. El extremo está preconfigurado con políticas en el proxy de API llamadas oauth. Puedes comenzar a usar el extremo del token en cuanto crees una cuenta en Apigee Edge.

El extremo de OAuth predeterminado expone el siguiente URI de extremo:

/oauth/client_credential/accesstoken

Publica este URI para los desarrolladores que necesiten obtener tokens de acceso. Los desarrolladores de apps configuran sus apps para llamar a este extremo y presentan sus pares de claves y secretos de consumidor para obtener tokens de acceso.

El extremo del token de credenciales de cliente predeterminado se expone en la red en la siguiente URL:

https://{org_name}-{env_name}.apigee.net/oauth/client_credential/accesstoken

Por ejemplo, si el nombre de su organización es "apimakers", la URL sería la siguiente:

https://apimakers-test.apigee.net/oauth/client_credential/accesstoken

Esta es la URL a la que los desarrolladores llaman para obtener tokens de acceso.

Opciones de configuración de OAuth de 3 segmentos

Las configuraciones de OAuth de tres segmentos (códigos de autorización, implícitos y tipos de otorgamiento de contraseña) requieren que, como proveedor de la API, autentiques a los usuarios finales de la app. Dado que cada organización autentica a los usuarios de diferentes maneras, se requiere cierta personalización de políticas o código para integrar OAuth en tu almacén de usuarios. Por ejemplo, todos los usuarios pueden estar almacenados en Active Directory, en un LDAP o en algún otro almacén de usuarios. Para poner en funcionamiento OAuth de tres segmentos, debes integrar una verificación de la tienda del usuario en el flujo general de OAuth.

OAuth 1.0a

Consulta la política de OAuth v1.0a para conocer los detalles de la política de OAuth 1.0a.

Obtén ayuda

Para obtener ayuda, consulta Asistencia al cliente de Apigee.