Proteger 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 tutorial se muestra cómo proteger un proxy de API mediante un token de acceso de OAuth 2.0.

Antes de empezar

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

  • Crear y desplegar proxies de APIs
  • Crear productos de API
  • Crear aplicaciones de desarrollador

También debes tener un nombre de host de grupo de entornos configurado correctamente con el que puedas hacer llamadas a proxies de API de Apigee. Si no sabes qué nombre de host de grupo de entornos usar, ponte en contacto con tu administrador de Apigee.

Implementar 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 desplegar este proxy de API en tu entorno:

Descarga el proxy de API de ejemplo oauth en un directorio de tu sistema de archivos.

Apigee en la consola de Cloud

  1. En la Google Cloud consola, ve a la página Desarrollo de proxy > Proxies de API.

    Ir a proxies de API

  2. En el panel Proxies de APIs, haz clic en + Crear.
  3. En el panel Crear un proxy, en Plantilla de proxy, seleccione Subir paquete de proxy.
  4. Elige el archivo oauth.zip que has descargado y haz clic en Siguiente.
  5. Haz clic en Siguiente.
  6. Implementar (opcional):
    • Entornos de implementación: opcional. Utilice las casillas de verificación para seleccionar uno o varios entornos en los que implementar su proxy. Si prefieres no implementar el proxy en este momento, deja el campo Entornos de implementación vacío. Puedes implementar el proxy más adelante.
    • Cuenta de servicio: opcional. Asocia una cuenta de servicio a tu implementación para que tu proxy pueda acceder a los servicios, tal como se especifica en el rol y los permisos de la cuenta de servicio. Google Cloud
  7. Haz clic en Crear.

Apigee Classic

  1. Ve a la interfaz de usuario de Apigee, inicia sesión y selecciona tu organización de Apigee.
  2. Seleccione Desarrollar > Proxies de API en la barra de navegación de la izquierda.
  3. Haz clic en Crear.
    Botón Crear proxy
  4. En el asistente Crear proxy, selecciona Subir paquete de proxy.
  5. Elige el archivo oauth.zip que has descargado y haz clic en Siguiente.
  6. Haz clic en Crear.
  7. Una vez que se haya completado la compilación, haz clic en Editar proxy para ver el nuevo proxy en el editor de proxies de API.
  8. Haz clic en Desplegar.
  9. Selecciona la revisión y el entorno en los que quieras realizar el despliegue. Puedes dejar el campo Cuenta de servicio en blanco.
  10. Haz clic en Desplegar.

Has descargado y desplegado correctamente un proxy de API que genera tokens de acceso en tu organización de Apigee.

Ver el flujo y la política de OAuth 2.0

Dedica unos minutos a examinar la configuración de la política de OAuth 2.0.

Consola de Apigee Cloud

A continuación, veremos más de cerca el contenido del proxy de API.

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

    Políticas mostradas en la pestaña Desarrollo.

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

  2. Haz clic en AccessTokenClientCredential en Proxy Endpoints (Endpoints de proxy). El editor de texto muestra el código XML del 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 condición determinada (se denomina "flujo condicional"). La condición, definida en el elemento <Condition>, indica que, si la llamada al proxy de API se hace al recurso /accesstoken y el verbo de la solicitud es POST, se debe ejecutar 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 del panel Solicitud: Haz clic en GenerateAccessTokenClient debajo de AccessTokenClientCredential.

Apigee Classic

A continuación, veremos más de cerca el contenido del proxy de API.

  1. En el editor de proxy de API, haz clic 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 (Endpoints de proxy).

  2. En Puntos finales de proxy, haz clic en AccessTokenClientCredential.
    Código XML del 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>, es que, si la llamada al proxy de API se realiza al recurso /accesstoken y el verbo de la solicitud es POST, se ejecute la política GenerateAccessTokenClient, que genera el token de acceso.

  3. Ahora veamos la política que activará el flujo condicional. En el diagrama de flujo, haz clic en el icono de la política GenerateAccessTokenClient.

    Icono de la política GenerateAccessTokenClient en el diagrama de flujo.

Se muestra la siguiente configuración 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:

  • El <Operation>, que puede ser uno de los varios valores predefinidos, define lo que va a hacer la política. En este caso, va a generar un token de acceso.
  • El token caducará 1 hora (3.600.000 milisegundos) después de generarse.
  • En <SupportedGrantTypes>, se espera que se use OAuth 2.0 <GrantType> client_credentials (intercambio de una clave y un secreto de consumidor por un token de OAuth 2.0).
  • El segundo elemento <GrantType> indica a la política dónde buscar el parámetro de tipo de concesión en la llamada a la API, tal como se especifica en la especificación de OAuth 2.0. (Verás esto en la llamada a la API más adelante). El tipo de concesión también se puede enviar en el encabezado HTTP (request.header.grant_type) o como parámetro de formulario (request.formparam.grant_type).

De momento, no tienes que hacer nada más con el proxy de la API. En pasos posteriores, usarás este proxy de API para generar un token de acceso de OAuth 2.0. Pero, antes, debes hacer algunas cosas más:

  • Crea el proxy de API que quieras proteger con OAuth 2.0.
  • Crea algunos artefactos más que generarán la clave de consumidor y el secreto de consumidor que necesitas para obtener un token de acceso.

Crear un proxy de API protegido

Ahora vas a crear el proxy de API que quieres proteger. Esta es la llamada a la API que devuelve algo que quieres. En este caso, el proxy de API llamará al servicio mocktarget de Apigee para devolver tu dirección IP. Sin embargo, solo podrás verlo si incluyes un token de acceso de OAuth 2.0 válido en tu llamada a la API.

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

Apigee en la consola de Cloud

  1. En la Google Cloud consola, ve a la página Desarrollo de proxy > Proxies de API.

    Ir a proxies de API

  2. En el panel Proxies de APIs, haz clic en + Crear.
  3. En el panel Crear un proxy, en Plantilla de proxy, selecciona Proxy inverso (el más habitual).
  4. Configura el proxy con lo siguiente:
    En este campo haz esto
    Nombre del proxy Introduce: helloworld_oauth2
    Ruta base

    Cambiar a: /hellooauth2

    La ruta base del proyecto forma parte de la URL que se usa para enviar solicitudes al proxy de la API.
    Descripción Introduce: hello world protected by OAuth 2.0
    Destino (API actual)

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

    Define la URL de destino que invoca Apigee en una solicitud al proxy de API.
  5. Haz clic en Siguiente.
  6. Implementar (opcional):
    • Entornos de implementación: opcional. Utilice las casillas de verificación para seleccionar uno o varios entornos en los que implementar su proxy. Si prefieres no implementar el proxy en este punto, deja el campo Entornos de implementación vacío. Puedes implementar el proxy más adelante.
    • Cuenta de servicio: opcional. Asocia una cuenta de servicio a tu implementación para que tu proxy pueda acceder a los servicios, tal como se especifica en el rol y los permisos de la cuenta de servicio. Google Cloud
  7. Haz clic en Crear.
  8. Haz clic en la pestaña Develop (Desarrollar) del proxy helloworld_oauth2.
  9. En el menú Políticas, haga clic en Añadir política.
  10. En el panel Crear política, selecciona OAuth 2.0.
  11. Haz clic en Crear.

Apigee Classic

  1. Ve a la interfaz de usuario de Apigee, inicia sesión y selecciona tu organización de Apigee.
  2. Seleccione Desarrollar > Proxies de API en la barra de navegación de la izquierda.
  3. Haz clic en Crear.
    Botón Crear proxy
  4. En el asistente para crear un proxy, selecciona Proxy inverso (el más habitual).
  5. Configura el proxy con lo siguiente:
    En este campo haz esto
    Nombre del proxy Introduce: helloworld_oauth2
    Ruta base del proyecto

    Cambiar a: /hellooauth2

    La ruta base del proyecto forma parte de la URL que se usa para enviar solicitudes al proxy de la API.
    API actual

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

    Define la URL de destino que invoca Apigee en una solicitud al proxy de API.
    Descripción Introduce: hello world protected by OAuth 2.0
  6. Haz clic en Siguiente.
  7. En la página Políticas comunes:
    En este campo haz esto
    Seguridad: autorización Selecciona:
    • OAuth 2.0

    Estas opciones son muy útiles. Se añadirán automáticamente dos políticas a tu proxy de API y se creará un producto de API.
  8. Haz clic en Siguiente.
  9. En la página Resumen, en Implementación opcional, selecciona un entorno y haz clic en Crear e implementar.
  10. Haz clic en Editar proxy para mostrar la página de descripción general del proxy de API.
    El proxy de API se desplegará automáticamente. (El despliegue puede tardar unos instantes en completarse).

Ver las políticas

Vamos a ver con más detalle lo que has creado.

Consola de Apigee Cloud

  1. En el editor de proxy de API, haz clic en la pestaña Desarrollar. Verás que se han añadido dos políticas al flujo de solicitudes del proxy de la API:
    • Verificar token de acceso de OAuth v2.0: comprueba la llamada a la API para asegurarse de que se incluye un token de OAuth 2.0 válido.
    • Eliminar autorización de encabezado: una política de asignación de mensajes que elimina el token de acceso después de comprobarlo para que no se transfiera al servicio de destino. Si el servicio de destino necesitara el token de acceso de OAuth 2.0, no usarías esta política.

  2. En el panel de la derecha, haz clic en el icono Verificar token de acceso de OAuth v2.0 y consulta el XML que aparece debajo en el editor de texto.

Apigee Classic

  1. En el editor de proxy de API, haz clic en la pestaña Desarrollar. Verás que se han añadido dos políticas al flujo de solicitudes del proxy de la API:
    • Verificar token de acceso de OAuth v2.0: comprueba la llamada a la API para asegurarse de que se incluye un token de OAuth 2.0 válido.
    • Eliminar autorización de encabezado: una política de asignación de mensajes que elimina el token de acceso después de comprobarlo para que no se transfiera al servicio de destino. Si el servicio de destino necesitara el token de acceso de OAuth 2.0, no usarías esta política.

  2. Haz clic en el icono Verificar token de acceso de OAuth v2.0 en la vista de flujo y consulta el XML que aparece debajo en el panel de código.

    Verificar el código del token de acceso de OAuth 2.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 el <Operation> es VerifyAccessToken. La operación define lo que debe hacer la política. En este caso, va a comprobar si hay un token de OAuth 2.0 válido en la solicitud.

Añadir un producto de API

Para obtener un token de acceso OAuth 2.0, debes crear tres entidades de Apigee: un producto de API, un desarrollador y una aplicación de desarrollador.

  1. Crea el producto de API:

    2. Apigee en la consola de Cloud

    En la consola de Google Cloud , ve a la página Distribución > Productos de API.

    Ir a productos de API

    Apigee Classic

    En la interfaz de usuario de Apigee, vaya a Publicar > Productos de API.

  2. Haz clic en + Crear.
  3. Introduce los detalles del producto de tu producto de API.
    Campo Descripción
    Nombre Nombre interno del producto de API. No especifiques caracteres especiales en el nombre.
    Nota: No puedes editar el nombre una vez que se haya creado el producto de API.
    Nombre visible Nombre visible del producto de la API. El nombre visible se usa en la interfaz de usuario y puedes editarlo en cualquier momento. Si no se especifica, se usará el valor de Name. Este campo se rellena automáticamente con el valor del nombre. Puede editar o eliminar su contenido. El nombre visible puede incluir caracteres especiales.
    Descripción Descripción del producto de la API.
    Entorno Entornos a los que permitirá acceder el producto de API. Selecciona el entorno en el que has desplegado el proxy de API.
    Acceso Selecciona Public (Públicas).
    Aprobar automáticamente las solicitudes de acceso Habilita la aprobación automática de solicitudes de claves para este producto de API desde cualquier aplicación.
    Cuota Ignóralo en este tutorial.
    Permisos de OAuth 2.0 permitidos Ignóralo en este tutorial.
  4. En la sección Operaciones, haz clic en Añadir una operación.
  5. En el campo Proxy de API, selecciona el proxy de API que acabas de crear.
  6. En el campo Ruta, introduce "/". Ignora los demás campos.
  7. Haz clic en Guardar para guardar la operación.
  8. Haz clic en Guardar para guardar el producto de la API.

Añadir un desarrollador y una aplicación a tu organización

A continuación, simularás el flujo de trabajo de un desarrollador que se registra para usar tus APIs. Lo ideal es que los desarrolladores registren sus aplicaciones a través de tu portal para desarrolladores. Sin embargo, en este paso añadirás un desarrollador y una aplicación como administradores.

Un desarrollador tendrá una o varias aplicaciones que llamen a tus APIs, y cada aplicación obtendrá una clave de consumidor y un secreto de consumidor únicos. Esta clave o secreto por aplicación también te ofrece, como proveedor de la API, un control más detallado sobre el acceso a tus APIs y un informe de analíticas más detallado sobre el tráfico de las APIs, ya que Apigee sabe a qué desarrollador y aplicación pertenece cada token de OAuth 2.0.

Crear un desarrollador

Vamos a crear un desarrollador llamado Nigel Tufnel.

Apigee en la consola de Cloud

  1. Abre el editor Desarrollador.

  2. En la Google Cloud consola, ve a la página Distribución > Desarrolladores.

    Ir a Desarrolladores

  3. Haz clic en + Crear.
  4. En la ventana Añadir desarrollador, introduce lo siguiente:
    En este campo Intro
    Nombre Nigel
    Apellidos Tufnel
    Correo electrónico nigel@example.com
    Username (Nombre de usuario) nigel
  5. Haz clic en Añadir.

Apigee Classic

  1. Abre el editor Desarrollador.

  2. En la interfaz de usuario de Apigee, vaya a Publicar > Desarrolladores.

  3. Haz clic en + Desarrollador.
  4. En la ventana Create a Developer (Crear desarrollador), introduce lo siguiente:
    En este campo Intro
    Nombre Nigel
    Apellidos Tufnel
    Correo electrónico nigel@example.com
    Username (Nombre de usuario) nigel
  5. Haz clic en Crear.

Registrar una aplicación

Vamos a crear una aplicación para Miguel.

Apigee en la consola de Cloud

  1. En la consola de Google Cloud , ve a la página Distribución > Aplicaciones.

    Ir a Aplicaciones

  2. Haz clic en + Crear.
  3. Introduce lo siguiente en la ventana Nueva aplicación:
    En este campo haz esto
    Nombre y Nombre visible Introduce: nigel_app
    Desarrolladores Haz clic en Desarrollador y selecciona: Nigel Tufnel (nigel@example.com)
    URL de retrollamada y Notas Dejar en blanco
  4. Haz clic en + Añadir credenciales.
  5. Haz clic en + Añadir productos.
  6. Selecciona el producto de API que acabas de crear.
  7. Haz clic en Añadir.
  8. Haz clic en Crear.

Apigee Classic

  1. En la interfaz de usuario de Apigee, vaya a Publicar > Desarrolladores.

  2. Haz clic en + Desarrollador.
  3. Haz clic en + Aplicación.
  4. Introduce lo siguiente en la ventana Nueva aplicación:
    En este campo haz esto
    Nombre y Nombre visible Introduce: nigel_app
    Desarrolladores Haz clic en Desarrollador y selecciona: Nigel Tufnel (nigel@example.com)
    URL de retrollamada y Notas Dejar en blanco
  5. En Productos, haga clic en Añadir producto.
  6. Añade el producto de API que acabas de crear.
  7. Haz clic en Crear.

Obtener la clave y el secreto del consumidor

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

  1. Abre la página nigel_app.

    2. Apigee en la consola de Cloud

    1. Comprueba que se muestre la página nigel_app. Si no es así, ve a la página Distribución > Aplicaciones.

      Ir a Aplicaciones

    2. En la página nigel_app, haz clic en en las columnas Clave y Secreto. Ten en cuenta que la clave y el secreto están asociados al producto de API que has creado anteriormente.

    Apigee Classic

    1. Comprueba que se muestre la página nigel_app. Si no es así, en la página Aplicaciones (Publicar > Aplicaciones), 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 y el secreto están asociados al producto de API que has creado anteriormente.

  2. Selecciona y copia los valores Clave y Secreto. Péguelos en un archivo de texto temporal. Los usarás en un paso posterior, en el que llamarás al proxy de API que intercambiará estas credenciales por un token de acceso de OAuth 2.0.

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

Prueba a llamar al proxy de API protegido que acabas de crear. Ten en cuenta que no estás enviando un token de acceso OAuth 2.0 en la llamada.

donde YOUR ENV_GROUP_HOSTNAME es el nombre de host del grupo de entornos. Consulta Buscar el nombre de host del grupo de entornos.

Como el proxy de API tiene la política Verificar token de acceso de OAuth v2.0 que comprueba si hay un token de OAuth 2.0 válido en la solicitud, la llamada debería fallar y mostrar el siguiente mensaje:

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

En este caso, el error es bueno. Esto significa que tu proxy de API es mucho más seguro. Solo las aplicaciones de confianza con un token de acceso de OAuth 2.0 válido pueden llamar a esta API correctamente.

Obtener un token de acceso OAuth 2.0

A continuación, usarás la clave y el secreto que has copiado y pegado en un archivo de texto para obtener un token de acceso OAuth 2.0. Ahora vas a hacer una llamada a la API de ejemplo oauth que has importado, que generará un token de acceso a la API.

Con esa clave y ese secreto, haz 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 hacer la llamada, client_id y client_secret deben ir en el cuerpo de la solicitud y deben ser x-www-form-urlencoded.

Deberías obtener una respuesta como esta:

{
  "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"
}

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

¿Qué acaba de pasar?

¿Recuerdas que antes has visto el flujo condicional del proxy oauth, el que decía que, si el URI del recurso es /accesstoken y el verbo de la solicitud es POST, se ejecutara la política de OAuth 2.0 GenerateAccessTokenClient que genera un token de acceso? Tu comando cURL cumplía esas condiciones, por lo que se ejecutó la política de OAuth 2.0. Ha verificado tu clave de consumidor y tu secreto de consumidor, y los ha cambiado por un token de OAuth 2.0 que caduca en una 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 la API. Haz la siguiente llamada cURL. Sustituye el nombre de tu 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 correcta al proxy de API que devuelva tu dirección IP. Por ejemplo:

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

Puedes repetir esa llamada a la API durante casi una hora, tras la cual el token de acceso caducará. Para hacer la llamada después de una hora, tendrás que generar un nuevo token de acceso siguiendo los pasos anteriores.

¡Enhorabuena! Has creado un proxy de API y lo has protegido exigiendo que se incluya un token de acceso de OAuth 2.0 válido en la llamada.

Temas relacionados