OAuth

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

OAuth surgió como el principal protocolo de autorización para las 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 que los usuarios finales de la app autoricen a las apps para que actúen en su nombre. Para ello, las apps obtienen tokens de acceso de los proveedores de API. El proveedor de API autentica las credenciales del usuario final de la app, se asegura de que el usuario haya autorizado la app y, luego, emite un token de acceso para la app. Cuando la app consume una API protegida, Apigee Edge verifica el token de acceso para asegurarse de que sea válido y no haya vencido. Como proveedor de API, debes exponer extremos que permitan que las apps obtengan tokens de acceso.

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

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

Para mayor comodidad, todas las organizaciones en 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 las credenciales de la app. Estas credenciales de la app son simplemente el par de clave y secreto del consumidor que Apigee Edge emite para cada app que se registra en una organización. "Credenciales de cliente" se refiere al par de clave y secreto del consumidor en sí.

Para obtener más información sobre la emisión de credenciales a las apps con los servicios para desarrolladores de Edge, consulta Registra apps y administra claves.

Por este motivo, es relativamente simple "aumentar" tu esquema de seguridad de la API de la validación de la clave de API a las credenciales de cliente de OAuth. Ambos esquemas usan la misma clave y secreto del 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 del consumidor y secreto generados para la app en tu organización para 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 ).

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

Protege tu API con una política

Antes de que puedas usar tokens de acceso, debes configurar tus APIs para validar los tokens de acceso de OAuth en el tiempo de ejecución. Para ello, configura un proxy de API para validar los tokens de acceso. Esto significa que cada vez que una app realiza una solicitud para consumir una de tus APIs, la app debe presentar un token de acceso válido junto con la solicitud a la API. Apigee Edge controla 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 proxy de API nuevo, puedes agregar funciones. Como se muestra a continuación, puedes agregar la verificación de tokens de acceso de OAuth 2.0 seleccionando el botón de selección junto a Proteger con tokens de acceso de OAuth v2.0. Cuando seleccionas esta opción, se adjuntarán dos políticas al proxy de API recién creado, una con el fin de verificar los tokens de acceso y la otra para quitar el token de acceso una vez que se haya verificado.

Además, cuando seleccionas la opción Proteger con tokens de acceso de OAuth v2.0 , la casilla de verificación Publicar API de productos se puede seleccionar y se selecciona de forma automática. Marca esta opción si quieres generar automáticamente un producto cuando compiles el proxy de API nuevo. El producto generado automáticamente se creará con una asociación al nuevo proxy de API. Si tienes un producto existente con el que quieres asociar esta API nueva, asegúrate de borrar esta casilla de verificación para no crear un producto innecesario. Para obtener información sobre productos, consulta ¿Qué es un producto de API?

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

Política VerifyOAuthTokens de tipo OAuthV2

Una política de ejemplo para validar tokens de acceso se ve de la siguiente manera. (La configuración se explica en la siguiente tabla).

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

Configuración de la política

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

En la lista de proxies de API, selecciona weatherapi.

En la Descripción general de weatherapi, selecciona la vista Desarrollar.

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

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

Dale a tu política un nombre descriptivo y asegúrate de seleccionar Adjuntar política, PreFlow de flujo y Solicitud como configuración de adjuntos de política.

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

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

Si trabajas de forma local en un editor de texto o IDE, adjunta la política al PreFlow de 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 solicitud, te aseguras de que la política siempre se aplique a todos los mensajes de solicitud.

Ahora protegiste una API con credenciales de cliente de OAuth 2.0. El siguiente paso es aprender cómo 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"de autorización" 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 adjunta una política de OAuthV2, Apigee Edge verificará que el token de acceso que se presenta sea válido y, luego, otorgará acceso a la API y mostrará el informe meteorológico a la app que realizó la solicitud.

Pero, ¿cómo obtienen las apps tokens de acceso? Lo abordaremos en la siguiente sección.

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

Las apps obtienen tokens de acceso presentando sus pares de clave y secreto del consumidor al token extremo. 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 API oauth API para obtener un token de acceso. Después de que la app tenga un token de acceso, puede llamar a weatherapi de forma repetida hasta que venza el token de acceso o se revoque.

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

Puedes obtener una clave y un secreto del consumidor registrando 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 muestran apps, puedes aprender a registrar una app en el tema llamado Registra apps y administra claves de API de API).

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

En la vista de detalles de la app que seleccionaste, observa los campos de Clave de consumidor y Secreto de consumidor. Estos dos valores son las credenciales de cliente que usará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"
}

Observa los valores de consumerKey y consumerSecret. Usas 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 para 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 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 en 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 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 del token de OAuth. El extremo está preconfigurado con políticas en el proxy de API llamado 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 presentar sus pares de clave y secreto del consumidor para obtener access tokens.

El extremo del token de credenciales de cliente predeterminado se expone a través de 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 llaman los desarrolladores para obtener tokens de acceso.

Configuraciones de OAuth de 3 segmentos

Las configuraciones de OAuth de 3 segmentos (código de autorización, tipos de otorgamiento implícito y de contraseña ) requieren que tú, el proveedor de 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 la política o código para integrar OAuth con tu almacén de usuarios. Por ejemplo, todos tus usuarios pueden almacenarse en Active Directory, en un LDAP o en algún otro almacén de usuarios. Para que OAuth de tres segmentos funcione, debes integrar una verificación en este almacén de usuarios en el flujo general de OAuth.

OAuth 1.0a

Para obtener detalles sobre la política de OAuth 1.0a, consulta la política de OAuth v1.0a.

Obtener ayuda

Para obtener ayuda, consulta Apigee Atención al cliente.