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

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

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

    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 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 o JWT no cliente para enviar solicitações autenticadas à API, ele precisa estar no cabeçalho de autorização de uma solicitação HTTP e ter as seguintes reivindicaçõ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.