Autenticação de Símbolo da Web JSON

A pesquisa vetorial suporta pontos finais de índice autenticados através de símbolos da Web JSON (JWTs) autoassinados. Para controlar o acesso ao ponto final do índice, este é configurado para aceitar apenas JWTs assinados emitidos por contas de serviço da Google especificamente autorizadas. Isto significa que apenas os clientes que usam essas contas designadas podem interagir com o ponto final.

Esta página descreve os passos necessários para configurar um ponto final de índice com autenticação de token da Web JSON (JWT) e executar consultas em relação ao mesmo.

Limitações

  • A autenticação JWT só é suportada para pontos finais privados com intercâmbio da VPC ou Private Service Connect (PSC).
  • A autenticação JWT só é suportada para APIs RPC do plano de dados (como o MatchService) que são invocadas através do gRPC. Os exemplos de RPC nesta página usam a ferramenta de código aberto grpc_cli para enviar pedidos gRPC para o servidor de índice implementado.
  • As APIs Admin para a criação, a implementação e a gestão de índices são protegidas através de funções de IAM predefinidas.

Criar e usar um JWT para consultar um índice

Siga estes passos para criar um ponto final de índice e consultá-lo com um JWT autoassinado.

Crie um índice

Crie um índice do Vector Search seguindo as instruções em Crie um índice.

Crie um ponto final privado

Crie um ponto final privado seguindo as instruções numa das seguintes páginas de documentação:

Criar uma conta de serviço

Crie uma conta de serviço e conceda-lhe a função da IAM Criador de tokens de conta de serviço.

  1. Ative a API IAM Service Account Credentials e crie uma conta de serviço:

    gcloud services enable iamcredentials.googleapis.com --project="PROJECT_ID"
gcloud iam service-accounts create SERVICE_ACCOUNT_ID --project="PROJECT_ID"

    Substitua os seguintes valores:

    • PROJECT_ID: o projeto no qual criar a sua conta de serviço.
    • SERVICE_ACCOUNT_ID: o ID da conta de serviço.

    Saiba mais sobre como criar uma conta de serviço.

  2. Use um dos seguintes comandos para conceder a função do IAM à sua conta de serviço:iam.serviceAccountTokenCreator

    • O comando seguinte concede-lhe autorização para criar JWTs através da conta de serviço de uma VM do Compute Engine que tenha a conta de serviço anexada:

      gcloud iam service-accounts add-iam-policy-binding \
   "SERVICE_ACCOUNT_ID@PROJECT_ID.iam.gserviceaccount.com" \
   --role "roles/iam.serviceAccountTokenCreator" \
   --member "serviceAccount:SERVICE_ACCOUNT_ID@PROJECT_ID.iam.gserviceaccount.com" \
   --project "PROJECT_ID"

      Substitua os seguintes valores:

      • SERVICE_ACCOUNT_ID: o ID da conta de serviço.
      • PROJECT_ID: o projeto no qual criar a sua conta de serviço.

    • O comando seguinte concede autorização para criar JWTs através da conta de serviço da sua própria Conta Google (na sua estação de trabalho):

      gcloud iam service-accounts add-iam-policy-binding \
   "SERVICE_ACCOUNT_ID@PROJECT_ID.iam.gserviceaccount.com" \
   --role "roles/iam.serviceAccountTokenCreator" \
   --member "user:EMAIL_ADDRESS" \
   --project PROJECT_ID

      Substitua os seguintes valores:

      • SERVICE_ACCOUNT_ID: o ID da conta de serviço.
      • PROJECT_ID: o projeto no qual criar a sua conta de serviço.
      • EMAIL_ADDRESS: o seu endereço de email.

Implemente o índice no ponto final com a configuração de autenticação JWT

  1. Implemente o índice no ponto final privado, conforme mostrado no exemplo seguinte:

    gcloud ai index-endpoints deploy-index INDEX_ENDPOINT_ID \
   --index=INDEX_ID \
   --deployed-index-id=DEPLOYED_INDEX_ID \
   --display-name=DEPLOYED_INDEX_NAME \
   --audiences=AUDIENCES \
   --allowed-issuers="SERVICE_ACCOUNT_ID@PROJECT_ID.iam.gserviceaccount.com" \
   --project=PROJECT_ID \
   --region=LOCATION

    Substitua os seguintes valores:

    • INDEX_ENDPOINT_ID: o ID do ponto final do índice.
    • INDEX_ID: o ID do índice.
    • DEPLOYED_INDEX_ID: uma string especificada pelo utilizador para identificar exclusivamente o índice implementado. Tem de começar com uma letra e conter apenas letras, números ou carateres de sublinhado. Consulte DeployedIndex.id para ver as diretrizes de formato.
    • DEPLOYED_INDEX_NAME: nome a apresentar do índice implementado.
    • AUDIENCES: uma string descritiva que identifica o público-alvo esperado para o seu serviço, carga de trabalho ou app, por exemplo, "123456-my-app".
    • SERVICE_ACCOUNT_ID: o ID da conta de serviço.
    • PROJECT_ID: o seu Google Cloud ID do projeto.
    • LOCATION: a região onde está a usar o Vertex AI.

Consulte o índice com um JWT autoassinado

A um nível elevado, os passos necessários são os seguintes:

  1. Crie uma carga útil JWT.
  2. Assine o token com a conta de serviço criada anteriormente.
  3. Consulte o índice através de uma chamada gRPC, transmitindo o token no cabeçalho de autorização.

Python

Crie e assine a carga útil JWT

Este exemplo usa o método sign_jwt da biblioteca de credenciais da API IAM Python para obter um token assinado. Para saber como instalar e usar esta biblioteca, consulte a documentação das bibliotecas cliente da API IAM.

   from google.cloud import iam_credentials_v1
   from datetime import datetime, timezone
   import json

   def sign_jwt(issuer: str, audience: str):
      client = iam_credentials_v1.IAMCredentialsClient()
      payload = {
            'aud': audience,
            'sub': audience,
            'iss': issuer,
            'iat': int(datetime.now(timezone.utc).timestamp()),
            'exp': int(datetime.now(timezone.utc).timestamp()) + 600,
      }
      response = client.sign_jwt(name="projects/-/serviceAccounts/" + issuer,
                                 payload=json.dumps(payload))
      return response.signed_jwt

   sign_jwt("SERVICE_ACCOUNT_ID@PROJECT_ID.iam.gserviceaccount.com",
            "AUDIENCES")

Linha de comandos

Crie a carga útil JWT

A autenticação da pesquisa vetorial aceita JWTs assinados com uma conta de serviço pré-autorizada para um público-alvo predefinido. O autor da chamada tem de especificar a conta de serviço e o público-alvo quando um índice é implementado num ponto final privado. Depois de implementar um índice com estas definições, todos os pedidos da API gRPC para esse ponto final têm de incluir um cabeçalho de autorização que contenha um JWT assinado pelo emissor (uma conta de serviço) e segmentado para o público fornecido. O JWT assinado é transmitido como um token de portador no cabeçalho authorization do pedido gRPC. Além de ser assinado pela conta de serviço, o JWT tem de incluir as seguintes reivindicações:

  • A reivindicação iss (emissor permitido) deve ser o endereço de email da conta de serviço, por exemplo:

    "iss": "SERVICE_ACCOUNT_ID@PROJECT_ID.iam.gserviceaccount.com"

  • As reivindicações aud (público) e sub (assunto) devem ser definidas com o mesmo valor. Esta é uma string descritiva que identifica o público-alvo esperado para o seu serviço, carga de trabalho ou app, por exemplo:

    "aud": "123456-my-app",
"sub": "123456-my-app"

    Este valor tem de corresponder ao argumento --audiences transmitido no momento da implementação.

  • A reivindicação iat (emitido a) deve ser definida para a hora em que o token é emitido. A reivindicação exp (hora de validade) deve ser definida para um curto período mais tarde (cerca de uma hora). Estes valores são expressos em tempo Unix epoch, por exemplo:

    "iat": 1698966927, // unix time since epoch eg via date +%s
"exp": 1698967527 // iat + a few mins (eg 600 seconds)

O exemplo seguinte mostra estas reivindicações num único payload JWT:

{
   "iss": "SERVICE_ACCOUNT_ID@PROJECT_ID.iam.gserviceaccount.com",
   "aud": "123456-my-app",
   "sub": "123456-my-app",
   "iat": 1698956084,
   "exp": 1698960084
}

A carga útil do JWT é assinada através da conta de serviço especificada na reivindicação iss.

Crie o JWT

  1. Certifique-se de que (o autor da chamada) pode usar a função roles/iam.serviceAccountTokenCreator na conta de serviço.

  2. Crie um ficheiro JSON denominado jwt_in.json que contenha o JWT não processado:

    SA="serviceAccount:SERVICE_ACCOUNT_ID@PROJECT_ID.iam.gserviceaccount.com"
cat << EOF > jwt_in.json
{
  "aud": "AUDIENCES",
  "sub": "AUDIENCES",
  "iss": "${SA}",
  "iat": $(date +%s),
  "exp": $(expr $(date +%s) + 600)
}
EOF

    Substitua os seguintes valores:

    • SERVICE_ACCOUNT_ID: o ID da conta de serviço.
    • PROJECT_ID: o seu Google Cloud ID do projeto.
    • AUDIENCES: uma string descritiva que identifica o público-alvo esperado para o seu serviço, carga de trabalho ou app, por exemplo, "123456-my-app".

Assine o JWT (API REST)

  1. Com a ferramenta jq, crie a curlcarga útil do pedido codificando o JWT numa string:

    cat jwt_in.json | jq -Rsa >request.json

  2. Assine o token transmitindo o payload do pedido ao método da API REST signJwt.

    SA="serviceAccount:SERVICE_ACCOUNT_ID@PROJECT_ID.iam.gserviceaccount.com"
curl -X POST \
   -H "Authorization: Bearer $(gcloud auth print-access-token)" \
   -H "Content-Type: application/json; charset=utf-8" \
   -d @request.json \
   "https://iamcredentials.googleapis.com/v1/projects/-/serviceAccounts/$SA:signJwt"

    Substitua os seguintes valores:

    • SERVICE_ACCOUNT_ID: o ID da conta de serviço.
    • PROJECT_ID: o seu Google Cloud ID do projeto.

    Armazene o valor signedJwt devolvido numa variável de ambiente denominada signedJwt.

Assine o JWT (CLI gcloud)

Em alternativa, pode assinar o JWT transmitindo o ficheiro jwt_in.json diretamente para o método sign-jwt da CLI gcloud.

gcloud iam service-accounts sign-jwt jwt_in.json jwt_out \
   --iam-account=SERVICE_ACCOUNT_ID@PROJECT_ID.iam.gserviceaccount.com

Substitua os seguintes valores:

  • SERVICE_ACCOUNT_ID: o ID da conta de serviço.
  • PROJECT_ID: o seu Google Cloud ID do projeto.

O JWT assinado é devolvido no ficheiro de saída jwt_out. Armazene-o numa variável de ambiente denominada signedJwt.

Envie o JWT assinado para o ponto final do índice

Python

Para saber como instalar ou atualizar o SDK Vertex AI para Python, consulte o artigo Instale o SDK Vertex AI para Python. Para mais informações, consulte a Python documentação de referência da API. 

def vector_search_match_jwt(
    project: str,
    location: str,
    index_endpoint_name: str,
    deployed_index_id: str,
    queries: List[List[float]],
    num_neighbors: int,
    signed_jwt: str,
) -> List[List[aiplatform.matching_engine.matching_engine_index_endpoint.MatchNeighbor]]:
    """Query the vector search index.

    Args:
        project (str): Required. Project ID
        location (str): Required. The region name
        index_endpoint_name (str): Required. Index endpoint to run the query
        against. The endpoint must be a private endpoint.
        deployed_index_id (str): Required. The ID of the DeployedIndex to run
        the queries against.
        queries (List[List[float]]): Required. A list of queries. Each query is
        a list of floats, representing a single embedding.
        num_neighbors (int): Required. The number of neighbors to return.
        signed_jwt (str): Required. The signed JWT token for the private
        endpoint. The endpoint must be configured to accept tokens from JWT's
        issuer and encoded audience.

    Returns:
        List[List[aiplatform.matching_engine.matching_engine_index_endpoint.MatchNeighbor]] - A list of nearest neighbors for each query.
    """
    # Initialize the Vertex AI client
    aiplatform.init(project=project, location=location)

    # Create the index endpoint instance from an existing endpoint.
    my_index_endpoint = aiplatform.MatchingEngineIndexEndpoint(
        index_endpoint_name=index_endpoint_name
    )

    # Query the index endpoint for matches.
    resp = my_index_endpoint.match(
        deployed_index_id=deployed_index_id,
        queries=queries,
        num_neighbors=num_neighbors,
        signed_jwt=signed_jwt,
    )
    return resp

Linha de comandos

A partir de uma VM do Compute Engine na mesma rede da VPC, chame o ponto final MatchService gRPC, transmitindo o token signedJwt no cabeçalho authorization, conforme mostrado no exemplo seguinte:

./grpc_cli call ${TARGET_IP}:10000 google.cloud.aiplatform.container.v1.MatchService.Match \
   '{deployed_index_id: "${DEPLOYED_INDEX_ID}", float_val: [-0.1,..]}' \
   --metadata "authorization: Bearer $signedJwt"

Para executar este comando, tem de definir as seguintes variáveis de ambiente:

  • TARGET_IP é o endereço IP do servidor de índice implementado. Para saber como obter este valor, consulte o artigo Consultar índices para obter os vizinhos mais próximos.
  • DEPLOYED_INDEX_ID: uma string especificada pelo utilizador para identificar exclusivamente o índice implementado. Tem de começar com uma letra e conter apenas letras, números ou carateres de sublinhado. Consulte DeployedIndex.id para ver as diretrizes de formato.

signedJwt é a variável de ambiente que contém o seu JWT assinado.

Resolução de problemas

A tabela seguinte apresenta algumas mensagens de erro gRPC comuns.

Mensagem de erro de gRPC Motivo
Não foi encontrado o cabeçalho de autorização para o índice "INDEX_ID" Os metadados gRPC não contêm um cabeçalho de autorização
O JWT tem um formato inválido O token tem um formato incorreto e não pode ser analisado corretamente
A autenticação JWT falhou O token expirou ou não está assinado pela conta de serviço correta
O emissor do JWT deve estar na lista de emissores permitidos O token iss não está nos emissores permitidos de auth_config
Falha na verificação de autorização para o índice "INDEX_ID" A reivindicação do token aud ou sub não está nos públicos-alvo auth_config

O que se segue?