Protege una API con OAuth

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

Qué aprenderás

  • Descargar e implementar un proxy de API de muestra
  • Crear un proxy de API protegido por OAuth
  • Crear un producto, un desarrollador y una app
  • Intercambiar las credenciales por un token de acceso de OAuth
  • Llamar a una API con un token de acceso

En este instructivo, se muestra cómo proteger una API con OAuth 2.0.

OAuth es un protocolo de autorización que permite que las apps accedan a información en nombre de los usuarios sin que estos tengan que revelar su nombre de usuario y contraseña.

Con OAuth, se intercambian las credenciales de seguridad (como el nombre de usuario y la contraseña, o la clave y el secreto) por un token de acceso. Por ejemplo:

joe:joes_password (nombre de usuario:contraseña) o
Nf2moHOASMJeUmXVdDhlMbPaXm2U7eMc:unUOXYpPe74ZfLEb (clave:secreto)

El ejemplo anterior se convierte en algo como lo siguiente:

b0uiYwjRZLEo4lEu7ky2GGxHkanN

El token de acceso es una string aleatoria de caracteres y es temporal (debe caducar después de un tiempo relativamente corto), por lo que pasarla a fin de autenticar a un usuario en el flujo de trabajo de una app es mucho más seguro que transmitir credenciales reales.

La especificación de OAuth 2.0 define diferentes mecanismos, llamados "tipos de otorgamiento", para distribuir tokens de acceso para apps. El tipo de otorgamiento más básico definido por OAuth 2.0 se denomina "credenciales de cliente". En este tipo de otorgamiento, los tokens de acceso de OAuth se generan a cambio de credenciales de clientes, que son pares clave de consumidor/secreto de consumidores, como el ejemplo anterior.

El tipo de otorgamiento de credenciales de cliente en Edge se implementa mediante políticas en proxies de API. Un flujo de OAuth típico consta de dos pasos:

  • Llama al proxy de API 1 para generar un token de acceso de OAuth desde las credenciales de cliente. Una política de OAuth v2.0 en el proxy de API controla esto.
  • Llama al proxy 2 de la API para enviar el token de acceso de OAuth en una llamada a la API. El proxy de API verifica el token de acceso mediante una política de OAuth v2.0.

Requisitos

  • Una cuenta de Apigee Edge Si aún no tienes una, puedes registrarte con las instrucciones que aparecen en Crea una cuenta de Apigee Edge.
  • Instala cURL en tu máquina para realizar llamadas a la API desde la línea de comandos.

Descarga e implementa un proxy de API para generar tokens

En este paso, crearás el proxy de API que genera un token de acceso de OAuth desde una clave de consumidor y un secreto del consumidor enviados en una llamada a la API. Apigee proporciona un proxy de API de muestra que hace esto. Descargará e implementará el proxy ahora y, luego, lo usará en el instructivo. (Podrías compilar este proxy de API con facilidad). Este paso de descarga e implementación es para tu comodidad y mostrarte lo fácil que es compartir proxies que ya se han creado).

  1. Descarga el archivo ZIP del proxy de API de muestra de "oauth" en cualquier directorio de tu sistema de archivos.
  2. Ve a https://apigee.com/edge and sign in.
  3. Selecciona Desarrollar > Proxies de API en la barra de navegación izquierda.
  4. Haz clic en + Proxy.
    Botón para Crear proxy
  5. En el asistente Crear proxy, haz clic en Subir paquete de proxy.
  6. Elige el archivo oauth.zip que descargaste y haz clic en Next.
  7. Haz 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. En la página Descripción general del editor de proxy de API, haz clic en el menú desplegable Implementación y selecciona prueba. Este es el entorno de pruebas en tu organización.

    En el mensaje de confirmación, haz clic en Implementar.
    Cuando vuelvas a hacer clic en el menú desplegable Deployment, verás un ícono verde que indica que el proxy se implementó en el entorno de pruebas.

¡Buen trabajo! Descargaste e implementaste un proxy de API de generación de tokens de acceso a tu organización de Edge.

Visualiza el flujo y la política de OAuth

Observemos en detalle el contenido del proxy de API.

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

    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 (se denomina flujo condicional). La condición, definida en el elemento <Condition>, indica que, si la llamada del proxy de la API se realiza al recurso /accesstoken y el verbo de 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 el ícono de la política GenerateAccessTokenClient en el diagrama de flujo.

    La siguiente configuración de XML se carga en la vista de código:

    <OAuthV2 name="GenerateAccessTokenClient">
        <!-- This policy generates an OAuth 2.0 access token using the client_credentials grant type -->
        <Operation>GenerateAccessToken</Operation>
        <!-- This is in millseconds, 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 que se espera usar es client_credentials (mediante el cambio de una clave de consumidor y un secreto por un token de OAuth).
    • 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. Pero primero debes seguir algunos pasos adicionales:

  • Crea el proxy de API que deseas proteger con OAuth.
  • 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 el proxy de API protegido por OAuth

Acerca del destino ficticio

El servicio mocktarget se aloja en Apigee y muestra datos simples. De hecho, puedes acceder a él en un navegador web. Haz clic en los siguientes vínculos para probarlo:

http://mocktarget.apigee.net/ip

El destino muestra lo que deberías ver cuando finalmente llamas a este proxy de API.

También puedes acceder a http://mocktarget.apigee.net/help para ver otros recursos de API disponibles en el destino ficticio.

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 válido con la llamada a la API.

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

  1. Selecciona Desarrollar > Proxies de API (Develop > API Proxies) en la barra de navegación izquierda.
  2. Haz clic en + Proxy.
    Botón para Crear proxy
  3. En el asistente Build a Proxy, selecciona Revertir proxy (más común) y haz clic en Siguiente.
  4. Configura el proxy con lo siguiente:
    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 invoca Apigee Edge en una solicitud al proxy de API.

    Descripción Ingresa: hello world protected by OAuth
  5. Presiona Siguiente.
  6. En la página Políticas comunes, haz lo siguiente:
    En este campo haz lo siguiente Sigue estas recomendaciones
    Seguridad: Autorización Seleccione: OAuth 2.0
  7. Presiona Siguiente.
  8. En la página Hosts virtuales, haz clic en Siguiente.
  9. En la página Compilación, asegúrate de que el entorno de pruebas esté seleccionado y haz clic en Crear e implementar.
  10. En la página Resumen, verás una confirmación de que tu nuevo proxy de API se creó correctamente y que el proxy de API se implementó en tu entorno de pruebas.
  11. Haz clic en Edit proxy para mostrar la página Overview del proxy de API.
    Observa que esta vez el proxy de API se implementa automáticamente. Haz clic en el menú desplegable Implementación para asegurarte de que haya un punto de implementación verde junto al entorno de “prueba”.

Visualiza las políticas

Analicemos con más detalle lo que creaste.

  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 válido.
    • Remove Header Authorization: Es una política de AttributionMessage que quita el token de acceso después de la verificación para que no se pase al servicio de destino. (si el servicio de destino necesita el token de acceso de OAuth, 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.

    <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 válido en la solicitud.

Agrega un producto de API

Para agregar un producto de API mediante la IU de Apigee, sigue estos pasos:

  1. Selecciona Publicar > Productos de API.
  2. Haz clic en + Producto de API.
  3. Ingresa 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 crea el producto de API. Por ejemplo: helloworld_oauth2-Product
    Nombre visible Nombre visible del producto de API. El nombre visible se usa en la IU y puedes editarlo 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 su contenido. El nombre visible puede incluir caracteres especiales. Por ejemplo, helloworld_oauth2-Product.
    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. Por ejemplo, test.
    Acceso 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 permitidos Ignora este instructivo.
  4. En el campo Proxies de API, selecciona el proxy de API que acabas de crear.
  5. En el campo Ruta, ingresa “/”. Ignora los demás campos.
  6. Haz clic en Guardar.

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 API, 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 API y un informe de estadísticas más detallado sobre el tráfico de API, ya que Edge sabe qué desarrollador y app pertenecen a qué token de OAuth.

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 New Developer, ingresa 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 Crear.

Registra una aplicación

Crearemos una app para Nigel.

  1. Selecciona Publicar > Apps.
  2. Haga clic en + Aplicación.
  3. En la ventana New App, ingresa 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. Selecciona helloworld_oauth2-Product.
  6. Haz 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.

  1. Asegúrate de que se muestre la página nigel_app. De lo contrario, 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/el secreto están asociados con “helloworld_oauth2-Product” que se creó de forma automática 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.

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

Por ejemplo, llama al proxy de API protegido que debe mostrar tu dirección IP. Ejecuta el siguiente comando cURL en una ventana de terminal y reemplaza el nombre de tu organización de Edge. La palabra test de la URL es el entorno de pruebas de tu organización, en el que implementaste los proxies. La ruta base del proxy es /hellooauth2, la misma que especificaste cuando creaste el proxy. Ten en cuenta que no estás pasando un token de acceso de OAuth en la llamada.

curl https://ORG_NAME-test.apigee.net/hellooauth2

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 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 válido pueden llamar a esta API de forma correcta.

Obtén un token de acceso de OAuth

Ahora llegamos a la gran recompensa. Estás a punto de usar la clave y el secreto que copiaste y pegaste en un archivo de texto para intercambiarlos por un token de acceso de OAuth. 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 ese secreto, realiza la siguiente llamada a cURL (ten en cuenta que el protocolo es https) y sustituye el nombre de tu organización Edge, tu clave y tu secreto cuando se indique:

curl -X POST -H "Content-Type: application/x-www-form-urlencoded" \
"https://ORG_NAME-test.apigee.net/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 al 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. Copia el valor de access_token (sin las comillas) y pégalo en el archivo de texto. La usarás en un momento.

¿Qué pasó?

¿Recuerdas cuando viste ese flujo condicional en el proxy oauth que decía si el URI del recurso es /accesstoken y el verbo de solicitud es POST para ejecutar la política de OAuth GenerateAccessTokenClient que genera un token de acceso? Tu comando cURL cumple con esas condiciones, por lo que se ejecutó la política de OAuth. Se verificó tu clave y el secreto de consumidor, y los intercambiaron por un token OAuth 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 tu organización de Edge y el token de acceso.

curl https://ORG_NAME-test.apigee.net/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 válido en la llamada.

Temas relacionados