Usa un método personalizado para autenticar usuarios

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

Para autenticar un usuario, una aplicación cliente debe enviar un token web JSON (JWT) en el encabezado de autorización de la solicitud HTTP a tu API de backend. El proxy de servicio extensible (ESP) valida el token en nombre de tu API, por lo que no es necesario agregar ningún código a la API para procesar la autenticación. Sin embargo, debes configurar tu documento de OpenAPI para que sea compatible con los métodos de autenticación que elegiste.

El ESP valida un JWT de forma eficaz mediante las claves públicas de la entidad emisora de JWT. El 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 venzan los JWT, lo que ocurra primero.

Antes de comenzar

  • Agrega el código de autenticación a tu aplicación cliente, de acuerdo con la documentación del proveedor de autenticación.

  • Cuando tu aplicación cliente envía una solicitud HTTP, el encabezado de autorización en la solicitud debe contener las siguientes reclamaciones JWT:
    • iss (Emisor)
    • sub (Asunto)
    • aud (Público)
    • iat (Hora de emisión)
    • exp (Fecha y hora de vencimiento)

Cómo configurar el ESP para que admita la autenticación de clientes

Debes tener un objeto de requisitos de seguridad y un objeto de definiciones de seguridad en tu documento de OpenAPI para que el ESP valide las reclamaciones en el JWT firmado.

Para que admita la autenticación personalizada:

  1. Agrega lo siguiente a la definición de seguridad del documento de tu 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. Agrega una sección de seguridad en el nivel de la API para aplicarlo en su totalidad o en el nivel de los métodos y así aplicarla a un método específico.

     security:
   - your_custom_auth_id: []

Puedes crear varias definiciones de seguridad en el documento de OpenAPI, pero cada definición debe tener una entidad emisora diferente. Si usas las secciones security a nivel de API y de los métodos, la configuración del nivel de los métodos anula la de la API.

El campo x-google-audiences no es obligatorio. El ESP acepta todos los JWT con el nombre del servicio de backend en el formato https://SERVICE_NAME en la reclamación aud. Para permitir que los ID de cliente adicionales accedan al servicio de backend, puedes especificar los ID de cliente permitidos en el campo x-google-audiences mediante valores separados por comas. Luego, el ESP acepta los JWT con cualquiera de los ID de cliente especificados en la reclamación aud.

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

  • Formato fijo 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 claves simétrico, configura x-google-jwks_uri como el URI de un archivo que contiene la string de clave codificada en base64url.

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

Ten en cuenta que omitir x-google-jwks_uri dará como resultado horas de inicio en frío más altos, ya que el ESP debe realizar una llamada remota adicional durante el inicio. 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 URI de JWKS estables.

También puedes personalizar las ubicaciones de JWT si agregas x-google-extensions. Para obtener más información, consulta las extensiones de openAPI.

Cómo hacer una llamada autenticada a una API de Endpoints

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

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

Aquí, TOKEN y ENDPOINTS_HOST son entornos variables que contienen el token de autenticación y el nombre de host de tu API de forma respectiva. Consulta Realiza una solicitud autenticada a una API de Endpoints si deseas obtener un código de muestra que envía una solicitud mediante el encabezado Authorization:Bearer.

Si no puedes usar el encabezado cuando envías la solicitud, puedes colocar el token de autenticación en un parámetro de consulta llamado access_token. Por ejemplo:

curl "${ENDPOINTS_HOST}/echo?access_token=${TOKEN}"

Recibe resultados autenticados en tu API

Por lo general, el ESP reenvía todos los encabezados que recibe. Sin embargo, anula el encabezado original Authorization cuando la dirección de backend se especifique mediante x-google-backend en la especificación de OpenAPI o BackendRule en la configuración del servicio de gRPC.

El ESP enviará el resultado de la autenticación en X-Endpoint-API-UserInfo a la API de backend. Recomendamos usar este encabezado en lugar del original Encabezado Authorization. Este encabezado es una cadena que codifica base64url un objeto JSON. El formato del objeto JSON difiere entre ESPv2 y ESP. Para ESPv2, el objeto JSON es exactamente la carga útil original de JWT. Para ESP, El objeto JSON usa diferentes nombres de campo y coloca la carga útil de JWT original en el campo claims. Consulta Controla JWT en el servicio de backend para obtener más información sobre el formato.

¿Qué sigue?