Autenticação de utilizadores

Esta página descreve como adicionar suporte na sua API para autenticação de utilizadores a partir de aplicações cliente através dos Cloud Endpoints Frameworks. Tenha em atenção que, atualmente, os clientes Android e JavaScript são suportados.

Os Frameworks de Endpoints suportam a autenticação de utilizadores a partir de aplicações cliente que usam qualquer uma das seguintes metodologias:

• Firebase Auth
• Auth0
• Tokens de ID da Google

Independentemente do método de autenticação que usar, em cada método da API em que quer verificar a autenticação adequada, tem de verificar se existe um User válido, conforme descrito nas secções seguintes:

• Autenticação com o Firebase Auth
• Autenticação com o Auth0
• Autenticação com tokens de ID da Google

Pré-requisitos

Esta página pressupõe que já:

• Criou um Google Cloud projeto.

• Gestão de APIs adicionada.

Autenticação com o Firebase Auth

Para suportar chamadas de clientes que usam o Firebase Auth:

1. Se ainda não o fez, crie um projeto do Firebase. Os projetos do Firebase são projetos da consola que usam os serviços do Firebase. Google Cloud Para mais informações, consulte O que é um projeto do Firebase? e a documentação do Firebase.

2. Adicione o seguinte à anotação de @Api ou método:

   • Adicione um parâmetro authenticators à anotação, definido com o valor {EspAuthenticator.class}.
   • Adicione um parâmetro issuers que contenha um conjunto @ApiIssuer definido para o Firebase.
   • Adicione um parâmetro issuerAudiences que contenha um @ApiIssuerAudience definido para o Firebase e o ID do projeto.

   Por exemplo:

   @Api(
       name = "YOUR_API_NAME",
       version = "VERSION_NUMBER",
       authenticators = {EspAuthenticator.class},
       issuers = {
           @ApiIssuer(
               name = "firebase",
               issuer = "https://securetoken.google.com/YOUR_PROJECT_ID",
               jwksUri = "https://www.googleapis.com/service_accounts/v1/metadata/x509/[e-mail]")
       },
       issuerAudiences = {
           @ApiIssuerAudience(name = "firebase", audiences = "YOUR_PROJECT_ID")
       })
   

   • Substitua YOUR_API_NAME pelo nome da sua API.
   • Substitua VERSION_NUMBER pela versão da sua API, por exemplo, v1.
   • Substitua ambas as instâncias de YOUR_PROJECT_ID pelo ID do projeto do Firebase.

3. No código de implementação da API, importe Users:

   import com.google.api.server.spi.auth.common.User;
   

4. Em cada método da API onde quer verificar a autenticação adequada, verifique se existe um User válido e lance uma exceção se não existir, conforme mostrado nesta definição de método de exemplo:

   @ApiMethod(httpMethod = ApiMethod.HttpMethod.GET)
   public Email getUserEmail(User user) throws UnauthorizedException {
     if (user == null) {
       throw new UnauthorizedException("Invalid credentials");
     }
   
     Email response = new Email();
     response.setEmail(user.getEmail());
     return response;
   }
   

5. Volte a implementar a API sempre que adicionar novos clientes.

Adicionar a Firebase Authentication a um cliente

Pode adicionar a autenticação do Firebase ao seu código, conforme descrito na documentação do Firebase. O cliente tem de ter um Google Cloud projeto associado e o ID do projeto tem de estar listado na configuração do emissor do Firebase da API, conforme mostrado na secção anterior.

Autenticação com o Auth0

Para suportar chamadas de clientes que usam o Auth0:

1. Adicione o seguinte à anotação de @Api ou método:

   • Adicione um parâmetro authenticators à anotação, definido com o valor {EspAuthenticator.class}.
   • Adicione um parâmetro issuers que contenha um @ApiIssuer definido como Auth0.
   • Adicione um parâmetro issuerAudiences que contenha um @ApiIssuerAudience definido como Auth0 e o seu ID de cliente do Auth0.

   Por exemplo:

   @Api(
       name = "YOUR_API_NAME",
       version = "VERSION_NUMBER",
       authenticators = {EspAuthenticator.class},
       issuers = {
           @ApiIssuer(
               name = "auth0",
               issuer = "https://YOUR_ACCOUNT_NAME.auth0.com/",
               jwksUri = "https://YOUR_ACCOUNT_NAME.auth0.com/.well-known/jwks.json")
        },
        issuerAudiences = {
            @ApiIssuerAudience(name = "auth0", audiences = "AUTH0_CLIENT_ID")
       })
   

   • Substitua YOUR_API_NAME pelo nome da sua API.
   • Substitua VERSION_NUMBER pela versão da sua API, por exemplo, v1.
   • Substitua YOUR_ACCOUNT_NAME pelo nome da conta do Auth0 usado para o cliente.
   • Substitua AUTH0_CLIENT_ID pelo ID que quer usar para o seu cliente.

2. No código de implementação da API, importe Users:

   import com.google.api.server.spi.auth.common.User;
   

3. Em cada método da API onde quer verificar a autenticação adequada, verifique se existe um User válido e lance uma exceção se não existir, conforme mostrado nesta definição de método de exemplo:

   @ApiMethod(httpMethod = ApiMethod.HttpMethod.GET)
   public Email getUserEmail(User user) throws UnauthorizedException {
     if (user == null) {
       throw new UnauthorizedException("Invalid credentials");
     }
   
     Email response = new Email();
     response.setEmail(user.getEmail());
     return response;
   }
   

4. Volte a implementar a API sempre que adicionar novos clientes.

Adicionar autenticação Auth0 a um cliente

Pode adicionar a autenticação Auth0 ao seu código, conforme descrito na documentação do Auth0. O cliente tem de estar listado na configuração do emissor Auth0 da API.

Autenticação com tokens de ID da Google

Para suportar chamadas de clientes que se autenticam através de tokens de ID da Google:

1. Obtenha um ID de cliente OAuth 2 para cada aplicação cliente. O proprietário da aplicação cliente tem de gerar o ID de cliente a partir da Google Cloud consola. Para ver instruções, consulte o artigo Criar IDs de clientes.

2. Adicione uma entrada clientIds que contenha o ID de cliente para cada app cliente à qual está a conceder acesso, bem como uma entrada audiences para cada cliente Android, na sua anotação @Api.

   Por exemplo:

   @Api(
      name = "YOUR_API_NAME",
      version = "VERSION_NUMBER",
      clientIds = {"YOUR_CLIENT_ID"},
      audiences = {"YOUR_CLIENT_ID"}
   )
   

   • Substitua YOUR_API_NAME pelo nome da sua API.
   • Substitua VERSION_NUMBER pela versão da sua API, por exemplo, v1.
   • Substitua YOUR_CLIENT_ID pelo ID de cliente OAuth 2 que foi gerado no projeto da aplicação cliente.

3. No código de implementação da API, importe Users:

   import com.google.api.server.spi.auth.common.User;
   

4. Em cada método da API onde quer verificar a autenticação adequada, verifique se existe um User válido e lance uma exceção se não existir, conforme mostrado nesta definição de método de exemplo:

   @ApiMethod(httpMethod = ApiMethod.HttpMethod.GET)
   public Email getUserEmail(User user) throws UnauthorizedException {
     if (user == null) {
       throw new UnauthorizedException("Invalid credentials");
     }
   
     Email response = new Email();
     response.setEmail(user.getEmail());
     return response;
   }
   

5. Volte a implementar a API sempre que adicionar novos clientes.

Adicionar autenticação de tokens de ID da Google a um cliente

Para obter informações sobre como adicionar o código de autenticação a clientes, consulte o seguinte:

• App Android

Enviar um JWT no seu cliente

Se usar um JWT no seu cliente para enviar pedidos autenticados para a API, o JWT tem de estar no cabeçalho de autorização de um pedido HTTP. O JWT deve ter as seguintes reivindicações obrigatórias:

• iss
• sub
• aud
• iat
• exp

O que se segue?

Para informações gerais sobre a autenticação de utilizadores e como difere da autorização da chave de API, consulte o artigo Quando e por que motivo usar chaves de API.