JSON Web Token authentication

Vector Search supports authenticated index endpoints using self-signed JSON Web Tokens (JWTs). To control access to the index endpoint, it's configured to accept only signed JWTs issued by specifically authorized Google service accounts. This means only clients using those designated accounts can interact with the endpoint.

This page outlines the required steps for setting up an index endpoint with JSON Web Token (JWT) authentication and running queries against it.

Limitations

• JWT authentication is supported only for private endpoints with VPC peering or Private Service Connect (PSC).
• JWT authentication is supported only for data plane RPC APIs (such as MatchService) that are invoked by using gRPC. The RPC examples in this page use the open source grpc_cli tool to send gRPC requests to the deployed index server.
• Admin APIs for creation, deployment, and management of indexes are secured by using predefined IAM roles.

Creating and using a JWT to query an index

Follow these steps to create an index endpoint and query it with a self-signed JWT.

Create an index

Create a Vector Search index by following the instructions in Create an index.

Create a private endpoint

Create a private endpoint by following the instructions in one of the following documentation pages:

• Set up a VPC Network Peering connection
• Vector Search Private Service Connect

Create a service account

Create a service account and grant it the Service Account Token Creator IAM role.

1. Enable the IAM Service Account Credentials API and create a service account:

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

   Replace the following values:

   • PROJECT_ID: The project to create your service account in.
   • SERVICE_ACCOUNT_ID: The ID for the service account.

   Learn more about creating a service account.

2. Use one of the following commands to grant the iam.serviceAccountTokenCreator IAM role to your service account:

   • The following command gives you permission to create JWTs by using the service account from a Compute Engine VM that has the service account attached to it:

     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"
     

     Replace the following values:

     • SERVICE_ACCOUNT_ID: The ID for the service account.
     • PROJECT_ID: The project to create your service account in.

   • The following command grants permission to create JWTs by using the service account from your own Google Account (on your workstation):

     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
     

     Replace the following values:

     • SERVICE_ACCOUNT_ID: The ID for the service account.
     • PROJECT_ID: The project to create your service account in.
     • EMAIL_ADDRESS: Your email address.

Deploy the index to the endpoint with JWT auth config

1. Deploy the index to the private endpoint as shown in the following example:

   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
   

   Replace the following values:

   • INDEX_ENDPOINT_ID: The ID of the index endpoint.
   • INDEX_ID: The ID of the index.
   • DEPLOYED_INDEX_ID: A user specified string to uniquely identify the deployed index. It must start with a letter and contain only letters, numbers or underscores. See DeployedIndex.id for format guidelines.
   • DEPLOYED_INDEX_NAME: Display name of the deployed index.
   • AUDIENCES: A descriptive string that identifies the expected audience for your service, workload or app, for example, "123456-my-app".
   • SERVICE_ACCOUNT_ID: The ID for the service account.
   • PROJECT_ID: Your Google Cloud project ID.
   • LOCATION: The region where you are using Vertex AI.

Query the index with a self-signed JWT

At a high level, the required steps are as follows:

1. Create a JWT payload.
2. Sign the token by using the service account created earlier.
3. Query the index by using a gRPC call, passing the token in the authorization header.

   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")

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

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

Send the signed JWT to the index endpoint

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

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

Troubleshooting

The following table lists some common gRPC error messages.

What's next

• To learn more about JWT and token claim structure, see RFC 7519.
• Learn more about how to Create a self-signed JSON Web Token (JWT)
• Learn how to Update and rebuild your index
• Learn how to Monitor an index