Autenticar usuarios mediante un método personalizado

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

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. El proxy de servicios extensible (ESP) valida el token en nombre de tu API, por lo que no tienes que añadir ningún código en tu API para procesar la autenticación. Sin embargo, debes configurar tu documento de OpenAPI para que admita los métodos de autenticación que elijas.

ESP valida un JWT de forma eficiente mediante las claves públicas del emisor del JWT. ESP almacena en caché las claves públicas durante cinco minutos. Además, el ESP almacena en caché los JWT validados durante cinco minutos o hasta que caduquen, lo que ocurra primero.

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 ESP para que admita la autenticación de clientes

Debes tener un objeto security requirement y un objeto security definitions en tu documento de OpenAPI para que ESP valide las reclamaciones del JWT firmado.

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

  1. Añade lo siguiente a la definición de seguridad de tu documento OpenAPI:

     securityDefinitions:
   your_custom_auth_id:
     authorizationUrl: ""
     flow: "implicit"
     type: "oauth2"
     # The value below should be unique
     x-google-issuer: "issuer of the token"
     x-google-jwks_uri: "url to the public key"
     # Optional. Replace YOUR-CLIENT-ID with your client ID
     x-google-audiences: "YOUR-CLIENT-ID"

  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: []

Puedes definir varias definiciones de seguridad en el documento de OpenAPI, 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 no es obligatorio. ESP 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 de backend, puede especificar los IDs de cliente permitidos en el campo x-google-audiences mediante valores separados por comas. A continuación, ESP acepta los JWTs con cualquiera de los IDs de cliente especificados en la reclamación aud.

ESP admite dos formatos de clave pública asimétrica definidos por la extensión x-google-jwks_uri OpenAPI:

  • Formato de conjunto de JWK. Por ejemplo: 
    x-google-jwks_uri: "https://YOUR_ACCOUNT_NAME.YOUR_AUTH_PROVIDER_URL/.well-known/jwks.json"
  • X509. Por ejemplo: 
    x-google-jwks_uri: "https://www.googleapis.com/service_accounts/v1/metadata/x509/securetoken@system.gserviceaccount.com"

Si usas un formato de clave simétrica, asigna a x-google-jwks_uri el URI de un archivo que contenga la cadena de clave codificada en base64url.

Si omite x-google-jwks_uri, ESP seguirá el protocolo OpenID Connect Discovery para descubrir automáticamente el URI de JWKS del proveedor de OpenID. El ESP hará una solicitud a x-google-issuer/.well-known/openid-configuration, analizará la respuesta JSON y leerá el URI de JWKS del campo jwks_uri de nivel superior.

Ten en cuenta que, si omites x-google-jwks_uri, los tiempos de arranque en frío serán más largos, ya que ESP tiene que hacer una llamada remota adicional al iniciarse. Por lo tanto, solo se recomienda omitir este campo si el URI de JWKS cambia con frecuencia. La mayoría de los proveedores de OpenID certificados (como Google, Auth0 y Okta) tienen URIs de JWKS estables.

También puedes personalizar las ubicaciones de JWT añadiendo x-google-extensions. Para obtener más información, consulta las extensiones de OpenAPI.

Hacer una llamada autenticada a una API de Endpoints

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

curl -H "Authorization: Bearer ${TOKEN}" "${ENDPOINTS_HOST}/echo"

Aquí, ENDPOINTS_HOST y TOKEN son variables de entorno que contienen tu nombre de host de la API y tu token de autenticación, respectivamente. Consulta Hacer una solicitud autenticada a una API de Endpoints 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 "${ENDPOINTS_HOST}/echo?access_token=${TOKEN}"

Recibir resultados autenticados en tu API

Normalmente, los ESP reenvían todos los encabezados que reciben. Sin embargo, anula el encabezado Authorization original cuando la dirección del backend se especifica mediante x-google-backend en la especificación de OpenAPI o BackendRule en la configuración del servicio gRPC.

El ESP enviará el resultado de la autenticación en el X-Endpoint-API-UserInfo a la API backend. Te recomendamos que uses este encabezado en lugar del encabezado Authorization original. Este encabezado es una cadena que base64url codifica un objeto JSON. El formato de objeto JSON es diferente en ESPv2 y ESP. En ESPv2, el objeto JSON es exactamente la carga útil del JWT original. En el caso de los ESPs, el objeto JSON usa nombres de campo diferentes y coloca la carga útil del JWT original en el campo claims. Consulta Gestionar JWTs en el servicio backend para obtener más información sobre el formato.

Siguientes pasos