Autenticação de utilizadores

A autenticação permite que o proxy de serviço extensível (ESP) identifique os utilizadores que chamam os métodos do seu serviço e, com base nisso, decida se os deixa usar esse método (autorização). Esta página descreve como a autenticação funciona com o Cloud Endpoints para serviços gRPC, incluindo como configurar o ESP num serviço gRPC para suportar pedidos autenticados e como chamar métodos autenticados a partir de um cliente gRPC.

O ESP suporta vários métodos de autenticação, incluindo Firebase, Auth0, e tokens de ID da Google, que podem ser configurados como parte da configuração da API gRPC. Em cada caso, o cliente tem de fornecer um símbolo da Web JSON (JWT) de identificação nos respetivos pedidos. O ESP valida o token em nome da sua API, pelo que não tem de adicionar nenhum código de autenticação especial.

Embora os requisitos de autenticação e chave de API lhe permitam restringir quem pode chamar os métodos do seu serviço, não oferecem o mesmo nível de segurança e fornecem informações diferentes ao serviço chamado. Pode saber mais sobre as diferenças entre as chaves da API e a autenticação, e quando é adequado usar cada esquema, em Quando e porquê usar chaves da API.

Para ver um exemplo de funcionamento completo que usa a autenticação, consulte o artigo Autenticação com uma conta de serviço, que adiciona autenticação ao serviço Bookstore dos nossos tutoriais.

Configurar a autenticação para o ESP

Configura a autenticação para um serviço Endpoints for gRPC no respetivo ficheiro YAML de configuração do serviço gRPC, usando a secção authentication. Especifica o método de autenticação e os detalhes da origem de autenticação como providers, onde:

  • O valor id é usado para identificar o fornecedor de autenticação quando usado em rules: normalmente, usa o nome do método de autenticação, mas não tem de o fazer.

  • O valor issuer é o emissor dos tokens necessários e, por isso, especifica o método de autenticação.

  • O valor jwks_uri é o URI da chave pública do fornecedor, usado para validar tokens. Alguns métodos de autenticação não requerem que especifique esta opção, como os tokens de ID da Google, em que o ESP obtém as informações automaticamente.

  • O jwt_locations é usado para definir as localizações a partir das quais o JWT é extraído.

Pode definir vários fornecedores de segurança no mesmo ficheiro, mas cada um tem de ter um issuer diferente. Consulte AuthProvider para mais informações.

Especifica os métodos API que quer usar estes requisitos de autenticação com rules, conforme descrito em AuthenticationRule.

Os exemplos seguintes mostram como configurar o ESP num serviço gRPC para alguns métodos de autenticação suportados:

firebase

Para suportar a autenticação do Firebase:

authentication:
  providers:
  - id: firebase
    jwks_uri: https://www.googleapis.com/service_accounts/v1/metadata/x509/securetoken@system.gserviceaccount.com
    # Replace FIREBASE-PROJECT-ID with your Firebase project ID
    issuer: https://securetoken.google.com/FIREBASE-PROJECT-ID
    audiences: "FIREBASE-PROJECT-ID"
    # Optional.
    jwt_locations:
    # expect header "jwt-header-foo": "jwt-prefix-foo<TOKEN>"
    - header: "jwt-header-foo"
      value_prefix: "jwt-prefix-foo"
    - query: "jwt_query_bar"
  rules:
  - selector: "*"
    requirements:
      - provider_id: firebase

auth0

Para suportar a autenticação do Auth0:

authentication:
  providers:
  - id: auth0_jwk
    # Replace YOUR-ACCOUNT-NAME with your service account's email address.
    issuer: https://YOUR-ACCOUNT-NAME.auth0.com/
    jwks_uri: "https://YOUR-ACCOUNT-NAME.auth0.com/.well-known/jwks.json"
    # Optional. Replace YOUR-CLIENT-ID with your client ID
    audiences: "YOUR-CLIENT-ID"
  rules:
  - selector: "*"
    requirements:
      - provider_id: auth0_jwk

Token de ID da Google

Para suportar a autenticação através de um token de ID Google:

authentication:
  providers:
  - id: google_id_token
    # This "issuer" field has to match the field "iss" in the JWT token.
     # Sometime it is "accounts.google.com".
    issuer: https://accounts.google.com
    # Optional. Replace YOUR-CLIENT-ID with your client ID
    audiences: "YOUR-CLIENT-ID"
  rules:
  - selector: "*"
    requirements:
      - provider_id: google_id_token

custom

Para suportar a autenticação personalizada:

authentication:
  providers:
  - id: custom_auth_id
    # The value below should be unique
    issuer: issuer of the token
    jwks_uri: url to the public key
    # Optional. Replace YOUR-CLIENT-ID with your client ID
    audiences: "YOUR-CLIENT-ID"
 rules:
 - selector: "*"
   requirements:
     - provider_id: custom_auth_id

Para a autenticação do Firebase, o campo audiences é obrigatório e tem de ser o ID do projeto do Firebase. Para todos os outros métodos de autenticação, é opcional. Se não for especificado, o ESP aceita todos os JWTs com o nome do serviço de back-end no formato https://SERVICE_NAME na reivindicação aud. Para permitir que IDs de clientes adicionais acedam ao serviço de back-end, pode especificar os IDs de clientes permitidos no campo audiences através de valores separados por vírgulas. Em seguida, o ESP aceita os JWTs com os IDs de clientes na lista de autorizações na reivindicação aud.

Chamar um método autenticado a partir do gRPC

Se um método requer autenticação, os clientes gRPC têm de transmitir o token de autenticação como metadados com a respetiva chamada de método, em que a chave é authorization e o valor é Bearer <JWT_TOKEN>. Veja um exemplo de como o fazer quando chama o exemplo da livraria em Python, Node.js ou Java:

Python

def run(
    host, port, api_key, auth_token, timeout, use_tls, servername_override, ca_path

Java

private static final class Interceptor implements ClientInterceptor {
  private final String apiKey;
  private final String authToken;

  private static Logger LOGGER = Logger.getLogger("InfoLogging");

  private static Metadata.Key<String> API_KEY_HEADER =
      Metadata.Key.of("x-api-key", Metadata.ASCII_STRING_MARSHALLER);
  private static Metadata.Key<String> AUTHORIZATION_HEADER =
      Metadata.Key.of("authorization", Metadata.ASCII_STRING_MARSHALLER);

  public Interceptor(String apiKey, String authToken) {
    this.apiKey = apiKey;
    this.authToken = authToken;
  }

  @Override
  public <ReqT, RespT> ClientCall<ReqT, RespT> interceptCall(
      MethodDescriptor<ReqT,RespT> method, CallOptions callOptions, Channel next) {
    LOGGER.info("Intercepted " + method.getFullMethodName());
    ClientCall<ReqT, RespT> call = next.newCall(method, callOptions);

    call = new ForwardingClientCall.SimpleForwardingClientCall<ReqT, RespT>(call) {
      @Override
      public void start(Listener<RespT> responseListener, Metadata headers) {
        if (apiKey != null && !apiKey.isEmpty()) {
          LOGGER.info("Attaching API Key: " + apiKey);
          headers.put(API_KEY_HEADER, apiKey);
        }
        if (authToken != null && !authToken.isEmpty()) {
          System.out.println("Attaching auth token");
          headers.put(AUTHORIZATION_HEADER, "Bearer " + authToken);
        }
        super.start(responseListener, headers);
      }
    };
    return call;
  }
}

Node.js

const makeGrpcRequest = (JWT_AUTH_TOKEN, API_KEY, HOST, GREETEE) => {
  // Uncomment these lines to set their values
  // const JWT_AUTH_TOKEN = 'YOUR_JWT_AUTH_TOKEN';
  // const API_KEY = 'YOUR_API_KEY';
  // const HOST = 'localhost:50051'; // The IP address of your endpoints host
  // const GREETEE = 'world';

  // Import required libraries
  const grpc = require('@grpc/grpc-js');
  const protoLoader = require('@grpc/proto-loader');
  const path = require('path');

  // Load protobuf spec for an example API
  const PROTO_PATH = path.join(__dirname, '/protos/helloworld.proto');

  const packageDefinition = protoLoader.loadSync(PROTO_PATH, {
    keepCase: true,
    longs: String,
    enums: String,
    defaults: true,
    oneofs: true,
  });

  const protoObj = grpc.loadPackageDefinition(packageDefinition).helloworld;

  // Create a client for the protobuf spec
  const client = new protoObj.Greeter(HOST, grpc.credentials.createInsecure());

  // Build gRPC request
  const metadata = new grpc.Metadata();
  if (API_KEY) {
    metadata.add('x-api-key', API_KEY);
  } else if (JWT_AUTH_TOKEN) {
    metadata.add('authorization', `Bearer ${JWT_AUTH_TOKEN}`);
  }

  // Execute gRPC request
  client.sayHello({name: GREETEE}, metadata, (err, response) => {
    if (err) {
      console.error(err);
    }

    if (response) {
      console.log(response.message);
    }
  });
};

A forma como o cliente obtém um JWT válido para enviar depende do método de autenticação.

Receber resultados da autenticação na sua API

Normalmente, o ESP encaminha todos os cabeçalhos que recebe. No entanto, 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 gRPC.

O ESP envia o resultado da autenticação no cabeçalho X-Endpoint-API-UserInfo para a API de back-end. Recomendamos que use este cabeçalho em vez do cabeçalho Authorization original. Este cabeçalho é uma string que base64urlcodifica um objeto JSON. O formato do objeto JSON difere entre o ESPv2 e o ESP. Para o ESPv2, o objeto JSON é exatamente o payload JWT original. Para o ESP, o objeto JSON usa nomes de campos diferentes e coloca o payload JWT original no campo claims. Consulte o artigo Processar JWTs no serviço de back-end para mais informações sobre o formato.

O que se segue?