Protege una API con OAuth 2.0

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

Consulta la documentación de Apigee Edge.

En este instructivo, se muestra cómo proteger un proxy de API con un token de acceso de OAuth 2.0.

Antes de comenzar

Para completar este instructivo, debes tener acceso a una organización de Apigee en la que tienes permiso para hacer lo siguiente:

  • Crear e implementar proxies de API
  • Crear productos de API
  • Crear apps para desarrolladores

También debes tener un nombre de host del grupo de entornos configurado correctamente con el que puedas realizar llamadas al proxy de API de Apigee. Si no estás seguro de qué nombre de host del grupo de entornos usar, consulta a tu administrador de Apigee.

Implementa el proxy de OAuth 2.0

Proporcionamos un proxy de API en GitHub que está configurado para generar tokens de acceso de OAuth 2.0. Sigue estos pasos para descargar y, luego, implementar este proxy de API en tu entorno:

  1. Descarga el proxy de API de muestra oauth en un directorio de tu sistema de archivos.
  2. Ve a la IU de Apigee y accede y selecciona tu organización de Apigee.
  3. Selecciona Desarrollar > Proxies de API en la barra de navegación izquierda.
  4. Haz clic en Crear nuevo.
    Botón para Crear proxy
  5. En el asistente de creación de proxy, selecciona Subir paquete de proxy.
  6. Elige el archivo oauth.zip que descargaste y haz clic en Siguiente.
  7. Haga clic en Crear.
  8. Una vez finalizada la compilación, haz clic en Editar proxy para ver el proxy nuevo en el editor de proxy de API.
  9. Haz clic en Implementar.
  10. Selecciona la revisión y el entorno en el que deseas realizar la implementación. Puedes dejar el campo Cuenta de servicio en blanco.
  11. Haz clic en Implementar.

Descargaste e implementaste un proxy de API de generación de tokens de acceso a tu organización de Apigee.

Visualiza el flujo y la política de OAuth 2.0

Tómate unos minutos para examinar la configuración de la política de OAuth 2.0.

Editor de proxies nuevo

A continuación, analizarás con más detalle lo que contiene el proxy de API.

  1. En el editor de proxy de API haga clic en la pestaña Desarrollar.

    Políticas que se muestran en la pestaña Desarrollar.

    En el panel de la izquierda, verás dos políticas. También verás dos flujos POST en la sección Proxy Endpoints.

  2. En extremos de proxy, haz clic en AccessTokenClientCredential. El editor de texto muestra el código XML para el flujo condicional AccessTokenClientCredential: 
    <Flow name="AccessTokenClientCredential">
    <Description/>
    <Request>
        <Step>
            <Name>GenerateAccessTokenClient</Name>
        </Step>
    </Request>
    <Response/>
    <Condition>(proxy.pathsuffix MatchesPath "/accesstoken") and (request.verb = "POST")</Condition>
</Flow>

    Un flujo es un paso de procesamiento en un proxy de API. En este caso, el flujo se activa cuando se cumple una determinada condición (lo que se denomina “flujo condicional”). La condición, definida en el elemento <Condition>, indica que la llamada al proxy de la API se realiza al recurso /accesstoken y el verbo de solicitud es POST. Luego, se ejecuta la política GenerateAccessTokenClient, que genera el token de acceso.

  3. Ahora veamos la política que activará el flujo condicional. Haz clic en la política GenerateAccessTokenClient en el panel Solicitud: Haz clic en GenerateAccessTokenClient debajo de AccessTokenClientCredential.

Editor de proxies clásico

A continuación, analizarás con más detalle lo que contiene el proxy de API.

  1. En el editor de proxy de API haga clic en la pestaña Desarrollar. En el panel del navegador de la izquierda, verás dos políticas. También verás dos flujos POST en la sección Proxy Endpoints.

  2. En extremos de proxy, haz clic en AccessTokenClientCredential.
    Código XML para el flujo condicional.

    En la vista de código XML, verás un Flow llamado AccessTokenClientCredential:

    <Flow name="AccessTokenClientCredential">
    <Description/>
    <Request>
        <Step>
            <Name>GenerateAccessTokenClient</Name>
        </Step>
    </Request>
    <Response/>
    <Condition>(proxy.pathsuffix MatchesPath "/accesstoken") and (request.verb = "POST")</Condition>
</Flow>

    Un flujo es un paso de procesamiento en un proxy de API. En este caso, el flujo se activa cuando se cumple una condición determinada. La condición, definida en el elemento <Condition>, indica que la llamada al proxy de la API se realiza al recurso /accesstoken y el verbo de solicitud es POST. Luego, se ejecuta la política GenerateAccessTokenClient, que genera el token de acceso.

  3. Ahora veamos la política que activará el flujo condicional. Haz clic en el ícono de la política GenerateAccessTokenClient en el diagrama de flujo.

    Ícono de la política GenerateAccessTokenClient en el diagrama de flujo.

Se muestra la siguiente configuración de XML:

<OAuthV2 name="GenerateAccessTokenClient">
    <!-- This policy generates an OAuth 2.0 access token using the client_credentials grant type -->
    <Operation>GenerateAccessToken</Operation>
    <!-- This is in milliseconds, so expire in an hour -->
    <ExpiresIn>3600000</ExpiresIn>
    <SupportedGrantTypes>
        <!-- This part is very important: most real OAuth 2.0 apps will want to use other
         grant types. In this case it is important to NOT include the "client_credentials"
         type because it allows a client to get access to a token with no user authentication -->
        <GrantType>client_credentials</GrantType>
    </SupportedGrantTypes>
    <GrantType>request.queryparam.grant_type</GrantType>
    <GenerateResponse/>
</OAuthV2>

La configuración incluye lo siguiente:

  • <Operation>, que puede ser uno de varios valores predefinidos, define lo que hará la política. En este caso, se generará un token de acceso.
  • El token vencerá 1 hora (3,600,000 milisegundos) después de generarse.
  • En <SupportedGrantTypes>, el <GrantType> de OAuth 2.0 que se espera usar es client_credentials (mediante el cambio de una clave de consumidor y un secreto por un token de OAuth 2.0).
  • El segundo elemento <GrantType> le indica a la política dónde buscar en la llamada a la API el parámetro de tipo de otorgamiento, según lo requiere la especificación de OAuth 2.0 (verás esto más adelante en la llamada a la API). El tipo de otorgamiento también podría enviarse en el encabezado HTTP (request.header.grant_type) o como un parámetro de formulario (request.formparam.grant_type).

No necesitas hacer nada más con el proxy de API en este momento. En pasos posteriores, usarás este proxy de API para generar un token de acceso de OAuth 2.0. Pero primero debes seguir algunos pasos adicionales:

  • Crea el proxy de API que deseas proteger con OAuth 2.0.
  • Crea algunos artefactos más que generarán la clave de consumidor y el secreto de consumidor que deberás intercambiar por un token de acceso.

Crea un proxy de API protegido

Ahora, creará el proxy de API que deseas proteger. Esta es la llamada a la API que muestra algo que deseas. En este caso, el proxy de API llamará al servicio de mocktarget de Apigee para que muestre tu dirección IP. Para verlo, solo podrás verlo si pasas un token de acceso de OAuth 2.0 válido con la llamada a la API.

El proxy de API que crees aquí incluirá una política que busca un token OAuth 2.0 en la solicitud.

  1. Selecciona Desarrollar > Proxies de API en la barra de navegación izquierda.
  2. Haz clic en Crear nuevo.
    Botón para Crear proxy
  3. En el asistente para compilar un proxy, selecciona Proxy inverso (más común).
  4. Configura el proxy con los siguientes pasos:
    En este campo haz lo siguiente Sigue estas recomendaciones
    Proxy name Ingresa: helloworld_oauth2
    Ruta de acceso base del proyecto

    Cambia a: /hellooauth2

    La ruta de acceso base del proyecto es parte de la URL que se usa para realizar solicitudes al proxy de API.
    Existing API

    Ingresa: https://mocktarget.apigee.net/ip

    Esto define la URL de destino que Apigee invoca en una solicitud al proxy de API.
    Descripción Ingresa: hello world protected by OAuth 2.0
  5. Haga clic en Next.
  6. En la página Políticas comunes, haz lo siguiente:
    En este campo haz lo siguiente Sigue estas recomendaciones
    Seguridad: Autorización Selecciona lo siguiente:
    • OAuth 2.0

    Estas opciones son muy útiles. Estos agregarán automáticamente dos políticas al proxy de API y crearán un producto de API.
  7. Haga clic en Siguiente.
  8. En la página Summary, en Optional Deployment, selecciona un entorno y haz clic en Create and Deploy.
  9. Haz clic en Editar proxy para mostrar la página de descripción general del proxy de API.
    El proxy de API se implementa de forma automática (la implementación podría tardar un momento en completarse).

Visualiza las políticas

Analicemos con más detalle lo que creaste.

Editor de proxies nuevo

  1. En el editor de proxy de API haga clic en la pestaña Desarrollar. Verás que se agregaron dos políticas al flujo de solicitudes del proxy de API:
    • Verifica el token de acceso para OAuth v2.0: verifica la llamada a la API a fin de asegurarte de que haya un token de OAuth 2.0 válido.
    • Quita la autorización del encabezado: una política de mensaje de asignación que quita el token de acceso después de que se verifica para que no se pase al servicio de destino (si el servicio de destino necesita el token de acceso de OAuth 2.0, no usarías esta política).

  2. Haz clic en el ícono Verify OAuth v2.0 Access Token en el panel derecho y observa el XML que aparece debajo en el editor de texto.

Editor de proxies clásico

  1. En el editor de proxy de API haga clic en la pestaña Desarrollar. Verás que se agregaron dos políticas al flujo de solicitudes del proxy de API:
    • Verifica el token de acceso para OAuth v2.0: verifica la llamada a la API a fin de asegurarte de que haya un token de OAuth 2.0 válido.
    • Quita la autorización del encabezado: una política de mensaje de asignación que quita el token de acceso después de que se verifica para que no se pase al servicio de destino (si el servicio de destino necesita el token de acceso de OAuth 2.0, no usarías esta política).

  2. Haz clic en el ícono Verificar token de acceso de OAuth v2.0 en la vista de flujo y observa el XML debajo del panel en el panel de código.

    Verifica el código del token de acceso de OAuth v2.0

<OAuthV2 async="false" continueOnError="false" enabled="true" name="verify-oauth-v2-access-token">
    <DisplayName>Verify OAuth v2.0 Access Token</DisplayName>
    <Operation>VerifyAccessToken</Operation>
</OAuthV2>

Ten en cuenta que <Operation> es VerifyAccessToken. La operación define lo que se supone que debe hacer la política. En este caso, verificará si hay un token de OAuth 2.0 válido en la solicitud.

Agrega un producto de API

Para obtener un token de acceso de OAuth 2.0, debes crear tres entidades de Apigee: un producto de API, un desarrollador y una app para desarrolladores. Primero, crea el producto de API:

  1. Selecciona Publicar > Productos de API.
  2. Haz clic en +Crear.
  3. Ingresa los detalles del producto para el producto de API.
    Campo Descripción
    Name Nombre interno del producto de API. No especifiques caracteres especiales en el nombre.
    Nota: No puedes editar el nombre una vez que se crea el producto de API.
    Nombre visible Nombre visible del producto de API. El nombre visible se usa en la IU y se puede editar en cualquier momento. Si no se especifica, se usará el valor Nombre. Este campo se completa automáticamente con el valor Nombre. Puedes editar o borrar tu contenido. El nombre visible puede incluir caracteres especiales.
    Descripción Descripción del producto de API.
    Entorno Entornos a los que el producto de API permitirá el acceso Selecciona el entorno en el que implementaste el proxy de API.
    Acceder Selecciona Público.
    Aprueba de manera automática las solicitudes de acceso Habilita la aprobación automática de solicitudes clave para este producto de API desde cualquier aplicación.
    Cuota Ignora este instructivo.
    Permisos de OAuth 2.0 permitidos Ignora este instructivo.
  4. En la sección Operaciones, haz clic en Agregar una operación.
  5. En el campo Proxy de API, selecciona el proxy de API que acabas de crear.
  6. En el campo Ruta, ingresa “/”. Ignora los otros campos.
  7. Haz clic en Guardar para guardar la operación.
  8. Haz clic en Save para guardar el producto de API.

Agrega un desarrollador y una app a tu organización

A continuación, simularás el flujo de trabajo de un desarrollador que se registra para usar tus API. Lo ideal sería que los desarrolladores se registren a sí mismos y a sus apps a través del portal para desarrolladores. Sin embargo, en este paso, agregarás un desarrollador y una app como administrador.

Un desarrollador tendrá una o más apps que llamarán a tus APIs, y cada app obtendrá un secreto y una clave de consumidor únicos. Esta clave/secreto por app también te proporciona un proveedor de API, un control más detallado sobre el acceso a tus APIs y un informe de estadísticas más detallado sobre el tráfico de API, ya que Apigee sabe qué desarrollador y app pertenecen a qué token de OAuth 2.0.

Cree un desarrollador

Crearemos un desarrollador llamado Nigel Tufnel.

  1. Selecciona Publicar > Desarrolladores en el menú.
  2. Haz clic en + Desarrollador.
  3. En la ventana Nuevo desarrollador, ingrese lo siguiente:
    En este campo haz lo siguiente Ingresa
    Nombre Nigel
    Apellido Tufnel
    Nombre de usuario nigel
    Correo electrónico nigel@example.com
  4. Haz clic en Guardar.

Registra una aplicación

Crearemos una app para Nigel.

  1. Selecciona Publicar > Apps.
  2. Haga clic en + Aplicación.
  3. En la ventana Nueva aplicación de desarrollador, ingrese lo siguiente:
    En este campo haz lo siguiente Sigue estas recomendaciones
    Nombre y Nombre visible Ingresa: nigel_app
    Desarrollador Haz clic en Desarrollador y selecciona: Nigel Tufnel (nigel@example.com)
    URL de devolución de llamada y Notas Déjelo en blanco
  4. En Productos, haz clic en Agregar producto.
  5. Agrega el producto de API que acabas de crear.
  6. Haga clic en Crear.

Obtén la clave y el secreto de consumidor

Ahora obtendrás la clave de consumidor y el secreto de consumidor que se intercambiarán por un token de acceso de OAuth 2.0.

  1. Asegúrate de que se muestre la página nigel_app. Si no, en la página Apps (Publicar > Apps), haz clic en nigel_app.

  2. En la página nigel_app, haz clic en Mostrar en las columnas Clave y Secreto. Ten en cuenta que la clave/secreta está asociada al producto de API que creaste antes.

  3. Selecciona y copia la clave y el secreto. Pégalos en un archivo de texto temporal. Las usarás en un paso posterior, donde llamas al proxy de la API que intercambia estas credenciales para un token de acceso OAuth 2.0.

Intenta llamar a la API para obtener tu dirección IP (fallida)

Intenta llamar al proxy de API protegido que acabas de crear. Ten en cuenta que no pasarás un token de acceso OAuth 2.0 en la llamada.

En el ejemplo anterior, YOUR ENV_GROUP_HOSTNAME es el nombre de host del grupo de entornos. Consulta Encuentra el nombre de host del grupo de entornos.

Debido a que el proxy de API tiene la política Verificar Token de acceso de OAuth v2.0 que busca un token de OAuth 2.0 válido en la solicitud, la llamada debe fallar con el siguiente mensaje:

{"fault":{"faultstring":"Invalid access token","detail":{"errorcode":"oauth.v2.InvalidAccessToken"}}}

En este caso, es correcto que falle. Esto significa que el proxy de API es mucho más seguro. Solo las apps de confianza con un token de acceso de OAuth 2.0 válido pueden llamar a esta API de forma correcta.

Obtén un token de acceso de OAuth 2.0

A continuación, usarás la clave y el secreto que copiaste y pegaste en un archivo de texto y los intercambiarás por un token de acceso OAuth 2.0. Ahora, harás una llamada a la API al proxy de API de muestra que importaste, oauth, que generará un token de acceso a la API.

Con esa clave y secreto, realiza la siguiente llamada cURL (ten en cuenta que el protocolo es https):

curl -X POST -H "Content-Type: application/x-www-form-urlencoded" \
"https://YOUR ENV_GROUP_HOSTNAME/oauth/client_credential/accesstoken?grant_type=client_credentials" \
-d "client_id=CLIENT_KEY&client_secret=CLIENT_SECRET"

Ten en cuenta que, si usas un cliente como Postman para realizar la llamada, client_id y client_secret van en el cuerpo de la solicitud y deben ser x-www-form-urlencoded.

Deberías obtener una respuesta como la siguiente:

{
  "issued_at" : "1466025769306",
  "application_name" : "716bbe61-f14a-4d85-9b56-a62ff8e0d347",
  "scope" : "",
  "status" : "approved",
  "api_product_list" : "[helloworld_oauth2-Product]",
  "expires_in" : "3599", //--in seconds
  "developer.email" : "nigel@example.com",
  "token_type" : "BearerToken",
  "client_id" : "xNnREu1DNGfiwzQZ5HUN8IAUwZSW1GZW",
  "access_token" : "GTPY9VUHCqKVMRB0cHxnmAp0RXc0",
  "organization_name" : "myOrg",
  "refresh_token_expires_in" : "0", //--in seconds
  "refresh_count" : "0"
}

Obtuviste tu token de acceso de OAuth 2.0. Copia el valor de access_token (sin comillas) y pégalo en el archivo de texto. La usarás en un momento.

¿Qué pasó?

¿Recuerdas anteriormente cuando viste ese “flujo condicional” en la OAuth proxy que indica si el URI del recurso es /accesstoken y el verbo de solicitud es POST, para ejecutar la política de OAuth 2.0 GenerateAccessTokenClient que genera un token de acceso? Tu comando cURL cumple con esas condiciones, por lo que se ejecutó la política de OAuth 2.0. Se verificó tu clave y el secreto de consumidor, y los intercambiaron por un token OAuth 2.0 que venció en 1 hora.

Llama a la API con un token de acceso (correcto)

Ahora que tienes un token de acceso, puedes usarlo para llamar al proxy de API. Realiza la llamada cURL siguiente. Sustituye el nombre de la organización de Apigee y el token de acceso.

curl https://YOUR ENV_GROUP_HOSTNAME/hellooauth2 -H "Authorization: Bearer TOKEN"

Ahora, deberías recibir una llamada exitosa al proxy de API que muestra tu dirección IP. Por ejemplo:

{"ip":"::ffff:192.168.14.136"}

Puedes repetir esa llamada a la API durante cerca de una hora, después de lo cual el token de acceso vencerá. Para realizar la llamada después de una hora, deberás generar un token de acceso nuevo mediante los pasos anteriores.

¡Felicitaciones! Creaste un proxy de API y lo protegiste mediante la solicitud de que se incluya un token de acceso OAuth 2.0 válido en la llamada.

Temas relacionados