Autenticar usuarios mediante JWT

En esta página se describe cómo admitir la autenticación de usuarios en API Gateway.

Para autenticar a un usuario, una aplicación cliente debe enviar un JSON Web Token (JWT) en el encabezado de autorización de la solicitud HTTP a tu API backend. La pasarela de APIs valida el token en nombre de tu API, por lo que no tienes que añadir ningún código a tu API para procesar la autenticación. Sin embargo, debes configurar la API de tu pasarela para que admita los métodos de autenticación que elijas.

API Gateway valida un JWT de forma eficiente mediante el conjunto de claves web de JSON (JWKS) del emisor del JWT. La ubicación de JWKS se especifica en la configuración de la API de la pasarela. API Gateway almacena en caché el JWKS durante cinco minutos y lo actualiza cada cinco minutos.

Antes de empezar

  • Añade el código de autenticación a tu aplicación cliente siguiendo la documentación del proveedor de autenticación.

  • Cuando tu aplicación cliente envía una solicitud HTTP, el encabezado de autorización de la solicitud debe contener las siguientes reclamaciones de JWT:
    • iss (emisor)
    • sub (asunto)
    • aud (audiencia)
    • iat (emitido a las)
    • exp (hora de vencimiento)

Configurar API Gateway para admitir la autenticación de clientes

Debes incluir una sección de seguridad en la configuración de tu API para que API Gateway valide las reclamaciones del JWT firmado. El esquema utilizado para definir los métodos de seguridad depende de la versión de la especificación de OpenAPI que utilices.

Para admitir la autenticación JWT, sigue estos pasos:

OpenAPI 2.0

  1. Añade lo siguiente a tu configuración de API: 
    securityDefinitions:
  your_custom_auth_id:
    authorizationUrl: ""
    flow: "implicit"
    type: "oauth2"
    # The issuer value should be unique
    x-google-issuer: "ISSUER"
    x-google-jwks_uri: "URL_PUBLIC_KEY"
    # Optional.
    x-google-audiences: "CLIENT_ID"

    Donde:

    • ISSUER es el emisor del token.
    • URL_PUBLIC_KEY es la URL de la clave pública.
    • CLIENT_ID es el ID de cliente.
  2. Añade una sección de seguridad a nivel de API para aplicarla a toda la API o a nivel de método para aplicarla a un método específico. 
    security:
  - your_custom_auth_id: []

OpenAPI 3.x

  1. Añade lo siguiente a tu configuración de API: 
    components:
  securitySchemes:
    SCHEME_NAME:
      type: oauth2
      flows:
       implicit:
         authorizationUrl: ""
         scopes: {}
      x-google-auth:
        issuer: ISSUER
        jwksUri: URL_PUBLIC_KEY
        # Optional. Replace CLIENT_ID with your client ID(s) as a list of strings.
        audiences:
          - CLIENT_ID
        jwtLocations:
          - header: Authorization
            valuePrefix: "Bearer "

    Donde:

    • ISSUER es el emisor del token.
    • URL_PUBLIC_KEY es la URL de la clave pública.
    • CLLIENT_ID es una lista de IDs de cliente en forma de cadenas.
  2. Añade una sección de seguridad a nivel de API para aplicarla a toda la API o a nivel de método para aplicarla a un método específico. 
    security:
  - SCHEME_NAME: []

Puedes definir varias definiciones de seguridad en la configuración de la API, pero cada definición debe tener un emisor diferente. Si usas secciones de seguridad tanto a nivel de API como a nivel de método, los ajustes a nivel de método anulan los ajustes a nivel de API.

El campo x-google-audiences (OpenAPI 2.0) o audiences (OpenAPI 3.x) no es obligatorio. API Gateway acepta todos los JWTs con el nombre del servicio de backend en el formato https://SERVICE_NAME en la reclamación aud.

Para permitir que otros IDs de cliente accedan al servicio backend, puedes especificar los IDs de cliente permitidos en el campo audiences correspondiente. Se especifican varias audiencias como valores separados por comas en OpenAPI 2.0 y con una lista en OpenAPI 3.x. A continuación, API Gateway acepta los JWTs con cualquiera de los IDs de cliente especificados en la reclamación aud.

El campo x-google-jwks_uri (OpenAPI 2.0) o jwksUri (OpenAPI 3.x) es obligatorio. API Gateway admite dos formatos de clave pública asimétrica definidos por esta extensión de OpenAPI:

  • Formato de conjunto de JWK. Por ejemplo:

    OpenAPI 2.0

    x-google-jwks_uri: "https://YOUR_ACCOUNT_NAME.YOUR_AUTH_PROVIDER_URL/.well-known/jwks.json"

    OpenAPI 3.x

    jwksUri: "https://YOUR_ACCOUNT_NAME.YOUR_AUTH_PROVIDER_URL/.well-known/jwks.json"
  • X509. Por ejemplo:

    OpenAPI 2.0

    x-google-jwks_uri: "https://www.googleapis.com/service_accounts/v1/metadata/x509/securetoken@system.gserviceaccount.com"

    OpenAPI 3.x

    jwksUri: "https://www.googleapis.com/service_accounts/v1/metadata/x509/securetoken@system.gserviceaccount.com"

Si usas un formato de clave simétrica, asigna al parámetro x-google-jwks_uri (OpenAPI 2.0) o jwksUri (OpenAPI 3.x) el URI de un archivo que contenga la cadena de clave codificada en base64url.

Hacer una llamada autenticada a una API de API Gateway

Cuando envíes una solicitud con un token de autenticación, te recomendamos que lo incluyas en el encabezado Authorization:Bearer. Por ejemplo:

curl -H "Authorization: Bearer TOKEN" "GATEWAY_URL/hello"

Aquí, GATEWAY_URL y TOKEN deben sustituirse por la URL de la pasarela implementada y el token de autenticación, respectivamente. Consulta el artículo Enviar una solicitud autenticada a una API de API Gateway para ver un ejemplo de código que envía una solicitud mediante el encabezado Authorization:Bearer.

Si no puedes usar el encabezado al enviar la solicitud, puedes incluir el token de autenticación en un parámetro de consulta llamado access_token. Por ejemplo: 

curl "GATEWAY_URL/hello?access_token=TOKEN"

Recibir resultados autenticados en tu API

API Gateway suele reenviar todos los encabezados que recibe. Sin embargo, anula el encabezado Authorization original cuando la dirección del backend se especifica mediante x-google-backend en la configuración de la API.

API Gateway enviará el resultado de la autenticación en el X-Apigateway-Api-Userinfo a la API de backend. Se recomienda usar este encabezado en lugar del encabezado Authorization original. Este encabezado está codificado en base64url y contiene la carga útil del JWT.

Siguientes pasos