Como usar o Auth0 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 aplicativo cliente de acordo com a documentação do Auth0.

  • Quando seu aplicativo cliente envia uma solicitação HTTP, o cabeçalho de autorização na solicitação deve conter as seguintes declarações do 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 (ambos em inglês) no documento da OpenAPI para que o ESP valide as declarações no JWT assinado.

Para aceitar a autenticação Auth0:

  1. Adicione o seguinte à definição de segurança no documento da OpenAPI:

      securityDefinitions:
    auth0_jwk:
      authorizationUrl: ""
      flow: "implicit"
      type: "oauth2"
      # Replace YOUR-ACCOUNT-NAME with your Auth0 account name.
      x-google-issuer: "https://YOUR-ACCOUNT-NAME.auth0.com/"
      x-google-jwks_uri: "https://YOUR-ACCOUNT-NAME.auth0.com/.well-known/jwks.json"
      # 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:
    - auth0_jwk: []

É 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.

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 denominado access_token. Por 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 em que base64url codifica um objeto JSON. O formato do objeto JSON é diferente entre o ESPv2 e o ESP. Para o ESPv2, o objeto JSON é exatamente o payload do JWT original. No ESP, o objeto JSON usa nomes de campos diferentes e coloca o payload original do JWT no campo claims. Consulte Gerenciar JWTs no serviço de back-end para mais informações sobre o formato.

Amostras

A seguir