Esta página foi traduzida pela API Cloud Translation.

Autenticação entre serviços

OpenAPI | gRPC

Além de autenticar utilizadores, pode ter de permitir que outros serviços interajam com a sua API. Embora as aplicações cliente possam apresentar aos utilizadores um pedido de início de sessão na Web para enviarem as respetivas credenciais, precisa de outra abordagem para a comunicação segura entre serviços. Esta página mostra a abordagem que recomendamos para implementar a autenticação entre serviços e fornece código de exemplo.

Vista geral

Para identificar um serviço que envia pedidos para a sua API, usa uma conta de serviço. O serviço de chamadas usa a chave privada da conta de serviço para assinar um símbolo da Web JSON (JWT) seguro e envia o JWT assinado no pedido para a sua API.

Para implementar a autenticação de serviço para serviço na sua API e serviço de chamadas:

Crie uma conta de serviço e uma chave para o serviço de chamadas usar.
Adicione suporte para autenticação no documento OpenAPI do seu serviço Cloud Endpoints.
Adicione código ao serviço de chamadas que:
- Cria um JWT e assina-o com a chave privada da conta de serviço.
- Envia o JWT assinado num pedido à API.

O ESP valida se as reivindicações no JWT correspondem à configuração no seu documento OpenAPI antes de encaminhar o pedido para a sua API. O ESP não verifica as autorizações do Cloud ID que concedeu na conta de serviço.

Pré-requisitos

Esta página pressupõe que já:

Criar uma conta de serviço com uma chave

Precisa de uma conta de serviço com um ficheiro de chave privada que o serviço de chamadas usa para assinar o JWT. Se tiver mais do que um serviço a enviar pedidos para a sua API, pode criar uma conta de serviço para representar todos os serviços de chamadas. Se precisar de distinguir os serviços, por exemplo, se tiverem autorizações diferentes, pode criar uma conta de serviço e uma chave para cada serviço de chamadas.

Esta secção mostra como usar a Google Cloud consola e a ferramenta de linha de comandos gcloud para criar a conta de serviço e o ficheiro de chave privada, e para atribuir à conta de serviço a função Criador de tokens de contas de serviço. Para obter informações sobre como usar uma API para realizar esta tarefa, consulte o artigo Criar e gerir contas de serviço.

Nota: As chaves de contas de serviço representam um risco de segurança se não forem geridas corretamente. Deve escolher uma alternativa mais segura às chaves de contas de serviço sempre que possível. Se tiver de fazer a autenticação com uma chave de conta de serviço, é responsável pela segurança da chave privada e por outras operações descritas nas Práticas recomendadas de gestão de chaves de conta de serviço. Se não conseguir criar uma chave de conta de serviço, a criação de chaves de contas de serviço pode estar desativada para a sua organização. Para mais informações, consulte o artigo Gerir recursos da organização seguros por predefinição.

Se adquiriu a chave da conta de serviço a partir de uma fonte externa, tem de a validar antes de a usar. Para mais informações, consulte os Requisitos de segurança para credenciais de origem externa.

Para criar uma conta de serviço e uma chave:

Google Cloud consola

Crie uma conta de serviço:
1. Na Google Cloud consola, aceda à página Criar conta de serviço.
  
  Aceda à página Criar conta de serviço
2. Selecione o projeto que quer usar.
3. No campo Nome da conta de serviço, introduza um nome.
4. Opcional: no campo Descrição da conta de serviço, introduza uma descrição.
5. Clique em Criar.
6. Clique em Concluído.
  
  Não feche a janela do navegador. Vai usá-lo no passo seguinte.
Crie uma chave de conta de serviço:
1. Na Google Cloud consola, clique no endereço de email da conta de serviço que criou.
2. Clique em Chaves.
3. Clique em Adicionar chave e, de seguida, em Criar nova chave.
4. Clique em Criar. Um ficheiro JSON que contém a chave privada da conta de serviço é transferido para o seu computador.
5. Clique em Fechar.

gcloud

Pode executar os seguintes comandos através da CLI Google Cloud no seu computador local ou no Cloud Shell.

Defina a conta predefinida para gcloud. Se tiver mais do que uma conta, certifique-se de que escolhe a conta que está no Google Cloud projeto que quer usar.
```
gcloud auth login
```
Apresentar os IDs dos seus Google Cloud projetos.
```
gcloud projects list
```
Defina o projeto predefinido. Substitua PROJECT_ID pelo ID do projeto que quer usar. Google Cloud
```
gcloud config set project PROJECT_ID
```
Crie uma conta de serviço. Substitua SA_NAME e SA_DISPLAY_NAME pelo nome e nome a apresentar que quer usar.
```
gcloud iam service-accounts create SA_NAME \
  --display-name "SA_DISPLAY_NAME"
```
Apresentar o endereço de email da conta de serviço que acabou de criar.
```
gcloud iam service-accounts list
```

Adicione a função Criador de tokens de contas de serviço. Substitua SA_EMAIL_ADDRESS pelo endereço de email da conta de serviço.

gcloud projects add-iam-policy-binding PROJECT_ID \
  --member serviceAccount:SA_EMAIL_ADDRESS \
  --role roles/iam.serviceAccountTokenCreator

Crie um ficheiro de chave de conta de serviço no diretório de trabalho atual. Substitua FILE_NAME pelo nome que quer usar para o ficheiro de chave. Por predefinição, o comando gcloud cria um ficheiro JSON.
```
gcloud iam service-accounts keys create FILE_NAME.json \
  --iam-account SA_EMAIL_ADDRESS
```

Consulte a gcloud referência para mais informações sobre os comandos anteriores.

Para obter informações sobre a salvaguarda da chave privada, consulte as Práticas recomendadas para gerir credenciais.

Configurar a API para suportar a autenticação

Para ativar a autenticação de contas de serviço para serviços que chamam o seu gateway, modifique os objetos de segurança no seu documento OpenAPI para que o ESP valide as reivindicações no JWT assinado. As modificações variam consoante a versão da especificação OpenAPI usada.

OpenAPI 2.0

Adicione a conta de serviço como emissor na sua especificação OpenAPI:

securityDefinitions:
    DEFINITION_NAME:
      authorizationUrl: ""
      flow: "implicit"
      type: "oauth2"
      x-google-issuer: "SA_EMAIL_ADDRESS"
      x-google-jwks_uri: "https://www.googleapis.com/robot/v1/metadata/x509/SA_EMAIL_ADDRESS"

Substitua DEFINITION_NAME por uma string que identifique esta definição de segurança. Pode querer substituí-lo pelo nome da conta de serviço ou por um nome que identifique o serviço de chamada.
Substitua SA_EMAIL_ADDRESS pelo endereço de email da conta de serviço.

Pode definir várias definições de segurança na sua especificação OpenAPI, mas cada definição tem de ter um x-google-issuer diferente. Se tiver criado contas de serviço separadas para cada serviço de chamadas, pode criar uma definição de segurança para cada conta de serviço, por exemplo:

securityDefinitions:
    service-1:
      authorizationUrl: ""
      flow: "implicit"
      type: "oauth2"
      x-google-issuer: "service-1@example-project-12345.iam.gserviceaccount.com"
      x-google-jwks_uri: "https://www.googleapis.com/robot/v1/metadata/x509/service-1@example-project-12345.iam.gserviceaccount.com"
    service-2:
      authorizationUrl: ""
      flow: "implicit"
      type: "oauth2"
      x-google-issuer: "service-2@example-project-12345.iam.gserviceaccount.com"
      x-google-jwks_uri: "https://www.googleapis.com/robot/v1/metadata/x509/service-2@example-project-12345.iam.gserviceaccount.com"

Opcionalmente, adicione x-google-audiences à secção securityDefinitions. Se não adicionar x-google-audiences, o ESP requer que a reivindicação "aud" (público-alvo) no JWT esteja no formato https://SERVICE_NAME, em que SERVICE_NAME é o nome do seu serviço ESP, que configurou no campo host do seu documento OpenAPI.
Adicione uma secção security no nível superior do ficheiro (não com recuo nem aninhada) para aplicar a toda a API ou no nível do método para aplicar a um método específico. Se usar secções security ao nível da API e ao nível do método, as definições ao nível do método substituem as definições ao nível da API.
```
security:
  - DEFINITION_NAME: []
```
- Substitua DEFINITION_NAME pelo nome que usou na secção securityDefinitions.
- Se tiver mais do que uma definição na secção securityDefinitions, adicione-as na secção security, por exemplo:
```
security:
  - service-1: []
  - service-2: []
```
Implemente a sua especificação OpenAPI atualizada. Antes de o ESP encaminhar um pedido para a sua API, o ESP valida:
- A assinatura do JWT através da chave pública, que se encontra no URI especificado no campo x-google-jwks_uri na sua especificação OpenAPI.
- Que a reivindicação "iss"(emissor) no JWT corresponde ao valor especificado no campo x-google-issuer.
- Que a reivindicação "aud"(público-alvo) no JWT contém o nome do serviço do ESP ou corresponde a um dos valores que especificou no campo x-google-audiences.
- Que o token não expirou através da reivindicação "exp"(tempo de expiração).

OpenAPI 3.x

Adicione a conta de serviço como emissor na sua especificação OpenAPI:

components:
  securitySchemes:
    SCHEME_NAME:
      type: oauth2
      flows:
       implicit:
         authorizationUrl: ""
         scopes: {}
      x-google-auth:
        issuer: SA_EMAIL_ADDRESS
        jwksUri: https://www.googleapis.com/robot/v1/metadata/x509/SA_EMAIL_ADDRESS
        audiences:
          - 848149964201.apps.googleusercontent.com
          - 841077041629.apps.googleusercontent.com
        jwtLocations:
          - header: Authorization
            valuePrefix: "Bearer "
security:
  - SCHEME_NAME: []

Substitua SCHEME_NAME por uma string que identifica este esquema de segurança. Recomendamos que o substitua pelo nome da conta de serviço ou por um nome que identifique o serviço de chamadas.
Substitua SA_EMAIL_ADDRESS pelo endereço de email da conta de serviço.

Pode definir vários esquemas de segurança na sua especificação OpenAPI, mas cada definição tem de ter um issuer diferente. Se tiver criado contas de serviço separadas para cada serviço de chamadas, pode criar uma definição de segurança para cada conta de serviço, por exemplo:

components:
  securitySchemes:
    service-1:
      type: oauth2
      flows:
       implicit:
         authorizationUrl: ""
         scopes: {}
      x-google-auth:
        issuer: "service-1@example-project-12345.iam.gserviceaccount.com"
        jwksUri: https://www.googleapis.com/robot/v1/metadata/x509/service-1@example-project-12345.iam.gserviceaccount.com
        jwtLocations:
          - header: Authorization
            valuePrefix: "Bearer "
    service-2:
      type: oauth2
      flows:
       implicit:
         authorizationUrl: ""
         scopes: {}
      x-google-auth:
        issuer: "service-2@example-project-12345.iam.gserviceaccount.com"
        jwksUri: "https://www.googleapis.com/robot/v1/metadata/x509/service-2@example-project-12345.iam.gserviceaccount.com"
        jwtLocations:
          - header: Authorization
            valuePrefix: "Bearer "

Opcionalmente, adicione audiences à secção securitySchemes. Se não adicionar audiences, o ESP requer que a reivindicação "aud" (público-alvo) no JWT esteja no formato https://SERVICE_NAME, em que SERVICE_NAME é o nome do seu serviço ESP, que configurou no campo host do seu documento OpenAPI.
Adicione uma secção security no nível superior do ficheiro (sem indentação nem aninhamento) para aplicar a toda a API ou no nível do método para aplicar a um método específico. Se usar secções security ao nível da API e ao nível do método, as definições ao nível do método substituem as definições ao nível da API.
```
security:
  - SCHEME_NAME: []
```
- Substitua SCHEME_NAME pelo nome que usou na secção securitySchemes.
- Se tiver mais do que uma definição na secção securitySchemes, adicione-as na secção security, por exemplo:
```
security:
  - service-1: []
  - service-2: []
```
Implemente a sua especificação OpenAPI atualizada. Antes de o ESP encaminhar um pedido para a sua API, o ESP valida:
- A assinatura do JWT através da chave pública, que se encontra no URI especificado no campo jwksUri na sua especificação OpenAPI.
- Que a reivindicação "iss"(emissor) no JWT corresponde ao valor especificado no campo issuer.
- Que a reivindicação "aud"(público-alvo) no JWT contém o nome do serviço do seu ESP ou corresponde a um dos valores que especificou no campo audiences.
- Que o token não expirou através da reivindicação "exp"(hora de validade).

Fazer um pedido autenticado a uma API Google Cloud Endpoints

Para fazer um pedido autenticado, o serviço de chamada envia um JWT assinado pela conta de serviço que especificou no documento OpenAPI. O serviço de chamadas tem de:

Crie um JWT e assine-o com a chave privada da conta de serviço.
Envie o JWT assinado num pedido à API.

O seguinte exemplo de código demonstra este processo para determinados idiomas. Para fazer um pedido autenticado noutros idiomas, consulte jwt.io para ver uma lista de bibliotecas suportadas.

No serviço de chamadas, adicione a seguinte função e transmita-lhe os seguintes parâmetros:

Java

saKeyfile: o caminho completo para o ficheiro da chave privada da conta de serviço.
saEmail: o endereço de email da conta de serviço.
audience: se adicionou o campo x-google-audiences ao seu documento OpenAPI, defina audience para um dos valores que especificou para x-google-audiences. Caso contrário, defina audience como https://SERVICE_NAME, onde SERVICE_NAME é o nome do serviço Endpoints.
expiryLength: o tempo de expiração do JWT, em segundos.

Python

sa_keyfile: o caminho completo para o ficheiro da chave privada da conta de serviço.
sa_email: o endereço de email da conta de serviço.
audience: se adicionou o campo x-google-audiences ao seu documento OpenAPI, defina audience para um dos valores que especificou para x-google-audiences. Caso contrário, defina audience como https://SERVICE_NAME, onde SERVICE_NAME é o nome do serviço Endpoints.
expiry_length: o tempo de expiração do JWT, em segundos.

saKeyfile: o caminho completo para o ficheiro da chave privada da conta de serviço.
saEmail: o endereço de email da conta de serviço.
audience: se adicionou o campo x-google-audiences ao seu documento OpenAPI, defina audience para um dos valores que especificou para x-google-audiences. Caso contrário, defina audience como https://SERVICE_NAME, onde SERVICE_NAME é o nome do serviço Endpoints.
expiryLength: o tempo de expiração do JWT, em segundos.

A função cria um JWT, assina-o através do ficheiro de chave privada e devolve o JWT assinado.

Java

/**
 * Generates a signed JSON Web Token using a Google API Service Account
 * utilizes com.auth0.jwt.
 */
public static String generateJwt(final String saKeyfile, final String saEmail,
    final String audience, final int expiryLength)
    throws FileNotFoundException, IOException {

  Date now = new Date();
  Date expTime = new Date(System.currentTimeMillis() + TimeUnit.SECONDS.toMillis(expiryLength));

  // Build the JWT payload
  JWTCreator.Builder token = JWT.create()
      .withIssuedAt(now)
      // Expires after 'expiryLength' seconds
      .withExpiresAt(expTime)
      // Must match 'issuer' in the security configuration in your
      // swagger spec (e.g. service account email)
      .withIssuer(saEmail)
      // Must be either your Endpoints service name, or match the value
      // specified as the 'x-google-audience' in the OpenAPI document
      .withAudience(audience)
      // Subject and email should match the service account's email
      .withSubject(saEmail)
      .withClaim("email", saEmail);

  // Sign the JWT with a service account
  FileInputStream stream = new FileInputStream(saKeyfile);
  ServiceAccountCredentials cred = ServiceAccountCredentials.fromStream(stream);
  RSAPrivateKey key = (RSAPrivateKey) cred.getPrivateKey();
  Algorithm algorithm = Algorithm.RSA256(null, key);
  return token.sign(algorithm);
}

Python

def generate_jwt(
    sa_keyfile,
    sa_email="account@project-id.iam.gserviceaccount.com",
    audience="your-service-name",
    expiry_length=3600,
):
    """Generates a signed JSON Web Token using a Google API Service Account."""

    now = int(time.time())

    # build payload
    payload = {
        "iat": now,
        # expires after 'expiry_length' seconds.
        "exp": now + expiry_length,
        # iss must match 'issuer' in the security configuration in your
        # swagger spec (e.g. service account email). It can be any string.
        "iss": sa_email,
        # aud must be either your Endpoints service name, or match the value
        # specified as the 'x-google-audience' in the OpenAPI document.
        "aud": audience,
        # sub and email should match the service account's email address
        "sub": sa_email,
        "email": sa_email,
    }

    # sign with keyfile
    signer = google.auth.crypt.RSASigner.from_service_account_file(sa_keyfile)
    jwt = google.auth.jwt.encode(signer, payload)

    return jwt


// generateJWT creates a signed JSON Web Token using a Google API Service Account.
func generateJWT(saKeyfile, saEmail, audience string, expiryLength int64) (string, error) {
	now := time.Now().Unix()

	// Build the JWT payload.
	jwt := &jws.ClaimSet{
		Iat: now,
		// expires after 'expiryLength' seconds.
		Exp: now + expiryLength,
		// Iss must match 'issuer' in the security configuration in your
		// swagger spec (e.g. service account email). It can be any string.
		Iss: saEmail,
		// Aud must be either your Endpoints service name, or match the value
		// specified as the 'x-google-audience' in the OpenAPI document.
		Aud: audience,
		// Sub and Email should match the service account's email address.
		Sub:           saEmail,
		PrivateClaims: map[string]interface{}{"email": saEmail},
	}
	jwsHeader := &jws.Header{
		Algorithm: "RS256",
		Typ:       "JWT",
	}

	// Extract the RSA private key from the service account keyfile.
	sa, err := os.ReadFile(saKeyfile)
	if err != nil {
		return "", fmt.Errorf("could not read service account file: %w", err)
	}
	conf, err := google.JWTConfigFromJSON(sa)
	if err != nil {
		return "", fmt.Errorf("could not parse service account JSON: %w", err)
	}
	block, _ := pem.Decode(conf.PrivateKey)
	parsedKey, err := x509.ParsePKCS8PrivateKey(block.Bytes)
	if err != nil {
		return "", fmt.Errorf("private key parse error: %w", err)
	}
	rsaKey, ok := parsedKey.(*rsa.PrivateKey)
	// Sign the JWT with the service account's private key.
	if !ok {
		return "", errors.New("private key failed rsa.PrivateKey type assertion")
	}
	return jws.Encode(jwsHeader, jwt, rsaKey)
}

No serviço de chamadas, adicione a seguinte função para enviar o JWT assinado no cabeçalho Authorization: Bearer no pedido à API:

Java

/**
 * Makes an authorized request to the endpoint.
 */
public static String makeJwtRequest(final String signedJwt, final URL url)
    throws IOException, ProtocolException {

  HttpURLConnection con = (HttpURLConnection) url.openConnection();
  con.setRequestMethod("GET");
  con.setRequestProperty("Content-Type", "application/json");
  con.setRequestProperty("Authorization", "Bearer " + signedJwt);

  InputStreamReader reader = new InputStreamReader(con.getInputStream());
  BufferedReader buffReader = new BufferedReader(reader);

  String line;
  StringBuilder result = new StringBuilder();
  while ((line = buffReader.readLine()) != null) {
    result.append(line);
  }
  buffReader.close();
  return result.toString();
}

Python

def make_jwt_request(signed_jwt, url="https://your-endpoint.com"):
    """Makes an authorized request to the endpoint"""
    headers = {
        "Authorization": "Bearer {}".format(signed_jwt.decode("utf-8")),
        "content-type": "application/json",
    }
    response = requests.get(url, headers=headers)
    print(response.status_code, response.content)
    response.raise_for_status()


// makeJWTRequest sends an authorized request to your deployed endpoint.
func makeJWTRequest(signedJWT, url string) (string, error) {
	client := &http.Client{
		Timeout: 10 * time.Second,
	}

	req, err := http.NewRequest("GET", url, nil)
	if err != nil {
		return "", fmt.Errorf("failed to create HTTP request: %w", err)
	}
	req.Header.Add("Authorization", "Bearer "+signedJWT)
	req.Header.Add("content-type", "application/json")

	response, err := client.Do(req)
	if err != nil {
		return "", fmt.Errorf("HTTP request failed: %w", err)
	}
	defer response.Body.Close()
	responseData, err := io.ReadAll(response.Body)
	if err != nil {
		return "", fmt.Errorf("failed to parse HTTP response: %w", err)
	}
	return string(responseData), nil
}

Quando envia um pedido através de um JWT, por motivos de segurança, recomendamos que coloque o token de autenticação no cabeçalho Authorization: Bearer. Por exemplo:

curl --request POST \
  --header "Authorization: Bearer ${TOKEN}" \
  "${ENDPOINTS_HOST}/echo"

onde ENDPOINTS_HOST e TOKEN são variáveis de ambiente que contêm o nome do anfitrião da API e o token de autenticação, respetivamente.

Receber resultados autenticados 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?

Resolução de problemas de validação de JWT

Autenticação entre serviços Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Vista geral

Pré-requisitos

Criar uma conta de serviço com uma chave

Google Cloud consola

gcloud

Configurar a API para suportar a autenticação

OpenAPI 2.0

OpenAPI 3.x

Fazer um pedido autenticado a uma API Google Cloud Endpoints

Receber resultados autenticados na sua API

O que se segue?

Autenticação entre serviços