Como autenticar usuários

Nesta página, você aprende como adicionar suporte à API para autenticação de usuários a partir de aplicativos cliente usando o Cloud Endpoints Frameworks. Atualmente, só há suporte para clientes Android e JavaScript.

O Endpoints Frameworks oferece suporte à autenticação de usuários de aplicativos clientes que usam qualquer uma das seguintes metodologias:

Não importa o método de autenticação usado, para verificar a autenticação adequada para cada método de API, é preciso checar se há User, conforme descrito nas seções a seguir:

Pré-requisitos

Nesta página, presume-se que você já:

Como autenticar com o Firebase Auth

Para oferecer suporte a chamadas de clientes que usam Firebase Auth, siga as etapas a seguir:

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

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

    • Adicione um parâmetro authenticators à anotação, defina o valor {EspAuthenticator.class}.
    • Adicione um parâmetro issuers que contém um conjunto @ApiIssuer ao Firebase.
    • Adicione um parâmetro issuerAudiences contendo um conjunto @ApiIssuerAudience ao Firebase e o ID do projeto.

    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/securetoken@system.gserviceaccount.com")
    },
    issuerAudiences = {
        @ApiIssuerAudience(name = "firebase", audiences = "YOUR_PROJECT_ID")
    })
    • Substitua YOUR_API_NAME pelo nome da API.
    • Substitua VERSION_NUMBER por sua versão da API, por exemplo, v1.
    • Substitua as duas 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 de API em que você quer verificar a autenticação adequada, confira se há User válido e lance uma exceção se não houver, como 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. Reimplante a API sempre que você adicionar novos clientes.

Adicionar Firebase Authentication a um cliente

É possível adicionar o Firebase Authentication ao código, conforme descrito na documentação do Firebase. O cliente precisa ter um projeto do Google Cloud associado a ele, e o ID do projeto precisa estar listado na configuração do emissor do Firebase da API, como mostrado na seção anterior.

Como autenticar com Auth0

Para oferecer suporte a chamadas de clientes que usam Auth0:

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

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

    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 API.
    • Substitua VERSION_NUMBER por sua versão da API, por exemplo, v1.
    • Substitua YOUR_ACCOUNT_NAME pelo nome da conta Auth0 usado para o cliente.
    • Substitua AUTH0_CLIENT_ID pelo código que você quer usar no 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 de API em que você quer verificar a autenticação adequada, confira se há User válido e lance uma exceção se não houver, como 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. Reimplante a API sempre que você adicionar novos clientes.

Adicionar a autenticação Auth0 a um cliente

Adicione a autenticação Auth0 ao código, conforme descrito na documentação do Auth0. O cliente precisa estar listado na configuração do emissor Auth0 da API.

Como autenticar com tokens de código do Google

Para oferecer suporte a chamadas de clientes que fazem a autenticação usando tokens de ID do Google:

  1. Receba um ID do cliente OAuth 2 para cada aplicativo cliente. O proprietário do aplicativo cliente precisa gerar o ID do cliente no console do Google Cloud. Para instruções, consulte Como criar IDs do cliente.

  2. Na sua anotação @Api, adicione uma entrada clientIds que contém o ID do cliente para cada aplicativo cliente a que você está concedendo acesso e uma entrada audiences também para cada cliente Android.

    Exemplo:

    @Api(
   name = "YOUR_API_NAME",
   version = "VERSION_NUMBER",
   clientIds = {"YOUR_CLIENT_ID"},
   audiences = {"YOUR_CLIENT_ID"}
)
    • Substitua YOUR_API_NAME pelo nome da API.
    • Substitua VERSION_NUMBER por sua versão da API, por exemplo, v1.
    • Substitua YOUR_CLIENT_ID pelo ID do cliente OAuth 2 gerado no projeto do aplicativo 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 de API em que você quer verificar a autenticação adequada, confira se há User válido e lance uma exceção se não houver, como 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. Reimplante a API sempre que você adicionar novos clientes.

Adicionar a autenticação de tokens de código do Google a um cliente

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

Como enviar um JWT em seu cliente

Se você usa um JWT no cliente para enviar solicitações autenticadas à API, ele precisa estar no cabeçalho de autorização de uma solicitação HTTP. O JWT precisa ter as seguintes declarações obrigatórias:

  • iss
  • sub
  • aud
  • iat
  • exp

A seguir

Para informações gerais sobre a autenticação de usuário e as diferenças entre esse método e a autorização de chave de API, consulte Quando e por que usar chaves de API.