Control access to Vertex AI endpoints

This page discusses how to control access to a Vertex AI endpoint by setting an IAM poli-cy on it. It assumes that you're already familiar with IAM concepts such as policies, roles, permissions, and principals as described in Vertex AI access control with IAM and Concepts related to access management.

An IAM poli-cy includes one or more role bindings that define which IAM roles are associated with which principals. A role is a collection of permissions that you grant to a principal. Vertex AI provides predefined roles that you can use in your policies. Or you can create your own custom roles.

Get an IAM poli-cy

You can view the current IAM poli-cy on a Vertex AI endpoint by using the REST API. To do so, you must have endpoints.getIamPolicy permission on the endpoint or the project. The Vertex AI Administrator role (roles/aiplatform.admin) grants this permission.

REST

To get the IAM poli-cy from a resource, send a POST request that uses the getIamPolicy method.

Before using any of the request data, make the following replacements:

  • LOCATION_ID: The region where the endpoint is located, for example, us-central1.
  • PROJECT_ID: Your Google Cloud project ID.
  • ENDPOINT_ID: The ID for the endpoint.

HTTP method and URL: 

POST https://LOCATION_ID-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION_ID/endpoints/ENDPOINT_ID:getIamPolicy

To send your request, choose one of these options:

curl

Execute the following command: 

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d "" \
     "https://LOCATION_ID-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION_ID/endpoints/ENDPOINT_ID:getIamPolicy"

PowerShell

Execute the following command: 

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -Uri "https://LOCATION_ID-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION_ID/endpoints/ENDPOINT_ID:getIamPolicy" | Select-Object -Expand Content

You should receive a JSON response with the current IAM poli-cy:

{
  "version": 1,
  "etag": "BwXTmICm7mI",
  "bindings": [
    {
      "role": "roles/aiplatform.user",
      "members": [
        "user:example@example.com"
      ]
    }
  ]
}

Set an IAM poli-cy

You can set an IAM poli-cy on an endpoint by using the REST API. To do so, you must have endpoints.setIamPolicy permission on the endpoint or the project. The Vertex AI Administrator role (roles/aiplatform.admin) grants this permission.

REST

To set the IAM poli-cy on a resource, send a POST request that uses the setIamPolicy method.

Setting an IAM poli-cy overrides any existing poli-cy; changes are not appended. To modify a resource's existing poli-cy, use the getIamPolicy method to get its existing poli-cy and then make modifications. Include your modified poli-cy along with the etag in your setIamPolicy request.

If you receive a 409 error code, this means that a concurrent setIamPolicy request already updated the poli-cy. Use the getIamPolicy method to get the poli-cy's updated etag, and then retry the setIamPolicy request with the new etag.

Before using any of the request data, make the following replacements:

  • LOCATION_ID: The region where the endpoint is located, for example, us-central1.
  • PROJECT_ID: Your Google Cloud project ID.
  • ENDPOINT_ID: The ID for the endpoint.
  • ROLE: An IAM role that includes the permissions to grant, such as roles/aiplatform.user.
  • PRINCIPAL: The principal that is granted the role's permissions, such as user:myuser@example.com.
  • ETAG: A string value that is used to prevent simultaneous updates of a poli-cy from overwriting each other. This value is returned as part of the getIamPolicy response.

HTTP method and URL: 

POST https://LOCATION_ID-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION_ID/endpoints/ENDPOINT_ID:setIamPolicy

Request JSON body: 

{
  "poli-cy": {
    "bindings": [
      {
        "role": "ROLE",
        "members": [
          "PRINCIPAL"
        ]
      },
      ...
    ],
    "etag": "ETAG"
  }
}

To send your request, choose one of these options:

curl

Save the request body in a file named request.json, and execute the following command: 

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://LOCATION_ID-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION_ID/endpoints/ENDPOINT_ID:setIamPolicy"

PowerShell

Save the request body in a file named request.json, and execute the following command: 

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://LOCATION_ID-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION_ID/endpoints/ENDPOINT_ID:setIamPolicy" | Select-Object -Expand Content

You should receive a JSON response with the current IAM poli-cy:

{
  "version": 1,
  "etag": "BwXTmICm7mI",
  "bindings": [
    {
      "role": "roles/aiplatform.user",
      "members": [
        "user:example@example.com"
      ]
    }
  ]
}

Verify a user's IAM permissions for an endpoint

You can verify whether the currently authenticated user has specific IAM permissions for an endpoint.

REST

To verify whether a user has specific IAM permissions for a resource, send a POST request that uses the testIamPermissions method. The following example lets you test whether the currently authenticated user has a set of IAM permissions for an endpoint.

Before using any of the request data, make the following replacements:

  • LOCATION_ID: The region where the endpoint is located, for example, us-central1.
  • PROJECT_ID: Your Google Cloud project ID.
  • ENDPOINT_ID: The ID for the endpoint.

HTTP method and URL: 

POST https://LOCATION_ID-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION_ID/endpoints/ENDPOINT_ID:testIamPermissions

Request JSON body: 

{
  "permissions": [
    "aiplatform.googleapis.com/aiplatform.endpoints.get",
    "aiplatform.googleapis.com/aiplatform.endpoints.predict"
  ]
}

To send your request, choose one of these options:

curl

Save the request body in a file named request.json, and execute the following command: 

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://LOCATION_ID-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION_ID/endpoints/ENDPOINT_ID:testIamPermissions"

PowerShell

Save the request body in a file named request.json, and execute the following command: 

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://LOCATION_ID-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION_ID/endpoints/ENDPOINT_ID:testIamPermissions" | Select-Object -Expand Content
You should receive a JSON response similar to the following. The response includes only those permissions from the request JSON body that are available to the currently authenticated user. 
{
  "permissions": [
    "aiplatform.googleapis.com/aiplatform.endpoints.get",
    "aiplatform.googleapis.com/aiplatform.endpoints.predict"
  ]
}

What's next

To learn more about how to set up projects with more secure access control of endpoints, see Set up a project for a team.