Como usar um método personalizado para autenticar usuários

Nesta página, você aprende como oferecer suporte à autenticação de usuário no Cloud Endpoints.

Para autenticar um usuário, um aplicativo cliente precisa enviar um token da Web do JSON (JWT, na sigla em inglês) no cabeçalho de autorização da solicitação HTTP para sua API de back-end. O Extensible Service Proxy (ESP) valida o token em nome da API, de modo que não é preciso adicionar nenhum código na API para processar a autenticação. No entanto, você precisa configurar o documento da OpenAPI para oferecer suporte aos métodos de autenticação escolhidos.

O ESP valida um JWT de maneira eficiente usando as chaves públicas do emissor do JWT. O ESP armazena as chaves públicas em cache por cinco minutos. Além disso, o ESP armazena em buffer os JWTs validados por cinco minutos ou até a expiração do JWT, o que ocorrer primeiro.

Antes de começar

  • Adicione o código de autenticação ao seu aplicativo cliente, seguindo a documentação do provedor de autenticação.

  • Quando seu aplicativo cliente envia uma solicitação HTTP, o cabeçalho de autorização na solicitação precisa conter as seguintes declarações JWT:
    • iss (emissor)
    • sub (assunto)
    • aud (público-alvo)
    • iat (emitido em)
    • exp (prazo de validade)

Como configurar o ESP para aceitar a autenticação de cliente

É preciso ter um objeto de requisito de segurança e um objeto de definições de segurança no documento OpenAPI para que o ESP valide as declarações no JWT assinado.

Para aceitar a autenticação personalizada:

  1. Adicione o seguinte à definição de segurança no documento da 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. Adicione uma seção de segurança no nível da API, para ser aplicável a toda a API, ou no nível do método, para ser aplicável a um método específico.

     security:
       - your_custom_auth_id: []
    

É possível estabelecer várias definições de segurança no documento da OpenAPI, mas cada uma delas precisa ter um emissor diferente. Se você usar seções "security" no nível da API e do método, as configurações no nível do método modificarão as configurações no nível da API.

O campo x-google-audiences não é obrigatório. O ESP é compatível com todos os JWTs que apresentam o nome do serviço de back-end no formato https://SERVICE_NAME na declaração aud. Para permitir outros IDs de cliente na lista de permissões de acesso ao serviço de back-end, especifique os IDs de cliente permitidos no campo x-google-audiences com valores separados por vírgulas. Em seguida, o ESP aceita os JWTs com qualquer um dos IDs de cliente especificados na declaração aud.

O ESP é compatível com dois formatos de chave pública assimétrica definidos pela extensão OpenAPI x-google-jwks_uri:

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

Se você estiver usando um formato de chave simétrica, defina x-google-jwks_uri como o URI de um arquivo que contém a string de chave codificada em base64url.

Se você omitir x-google-jwks_uri, o ESP seguirá o protocolo Descoberta do OpenID Connect para descobrir automaticamente o URI JWKS para o provedor OpenID fornecido. O ESP fará uma solicitação para x-google-issuer/.well-known/openid-configuration, analisará a resposta JSON e lerá o URI JWKS do campo de nível superior jwks_uri.

Observe que a omissão de x-google-jwks_uri resultará em tempos de inicialização a frio mais altos, já que o ESP precisará fazer uma chamada remota extra na inicialização. Portanto, é recomendável omitir esse campo apenas se o URI de JWKS for alterado com frequência. A maioria dos provedores OpenID certificados, como Google, Auth0 e Okta, tem URIs JWKS estáveis.

Você também pode personalizar os locais do JWT adicionando x-google-extensions. Para detalhes, consulte extensões da OpenAPI.

Como fazer uma chamada autenticada para uma Endpoints API

Quando enviar uma solicitação usando um token de autenticação, recomendamos que você coloque o token no cabeçalho Authorization:Bearer. Exemplo:

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

Aqui, ENDPOINTS_HOST e TOKEN são variáveis de ambiente contendo o nome do host da API e o token de autenticação, respectivamente. Consulte Como fazer uma solicitação autenticada para uma API Endpoints. Para o código de amostra que envia uma solicitação usando o cabeçalho Authorization:Bearer.

Se não for possível usar o cabeçalho ao enviar a solicitação, coloque o token de autenticação em um parâmetro de consulta chamado access_token. Exemplo:

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

Como receber resultados autenticados na API

O ESP geralmente encaminha todos os cabeçalhos recebidos. No entanto, ele substitui o cabeçalho Authorization original quando o endereço de back-end é especificado por x-google-backend na especificação OpenAPI ou BackendRule na configuração do serviço de gRPC.

O ESP enviará o resultado da autenticação no X-Endpoint-API-UserInfo para a API de back-end. Recomendamos usar esse cabeçalho em vez do cabeçalho Authorization original. Esse cabeçalho é uma string que base64url codifica um objeto JSON. O formato de objeto JSON é diferente no ESPv2 e no ESP. Para o ESPv2, o objeto JSON é exatamente o payload JWT original. Para o ESP, o objeto JSON usa nomes de campo diferentes e coloca o payload do JWT original no campo claims. Consulte Gerenciar JWTs no serviço de back-end para mais informações sobre o formato.

A seguir