Users and Access Control

Users

Users are entities that can interact with the Vertex.

They can be created and managed using the Vertex REST API Admin accessible endpoints.

A User is identified by its unique user_id and optionally by user_name and can interact with the Vertex using API Keys or a JWT-based authentication method (currently, only GCP service accounts are supported).

It is recommended to use different Users for different machines using the Vertex for different purposes.

Users are classified with respect to their Roles. Each User is assigned one or more Roles from a preconfigured list of available Roles listed below.

User Authentication Methods

Vertex supports multiple authentication methods for users:

1. API Key (classic) - Authenticate using a Vertex-generated API key placed in the Authorization header of the REST API request.
2. GCP Workload Identity - Authenticate using a GCP identity token (JWT). The token is obtained from GCP's metadata server for the service account associated with the workload.

When making REST API requests, place either the API key or the cloud provider identity token in the Authorization header. Vertex will validate JWTs and match them to users, or use the API key for classic authentication.

Security Note

Identity tokens are valid only for one vertex. Custom fields are used to bind tokens to a specific vertex instance, preventing cross-vertex token usage in the case of multi-vertex deployments (e.g. MPC cluster).

System Roles

Each endpoint exposed by the Vertex is one of two kinds:

1. A public endpoint where no authentication is required (no API Key needed).
2. A private endpoint that can only be called by authorized Users. A User is authorized to access the endpoint only when they provide a valid API key and have the appropriate Role to execute the request.

The following table is a comprehensive listing of all roles in the system:

Role Name	Description
SystemAdmin	Performs all administrative operations (i.e. manage Users and Policies)
PoliciesManager	Manages Policies and Rules (can create, delete, etc.)
ResourceViewer	Views Users, Keys, Policies, Rules, etc.
CryptoUser	Initiates crypto operations (i.e. sign, derive-pubkey)
KeysManager	Can manage key lifecycle (can create, delete, refresh, reshare, etc.)
KeysImporter	Can only import keys
KeysExporter	Can only export keys

For each API endpoint, all Roles that are authorized to call the endpoint are noted in its API Reference page.

Backwards Compatibility

All /admin endpoints remain accessible by the Admin Token set in the Vertex startup configuration in addition to Users with sufficient Roles.

Users & Roles

Every User is created with a set of Roles - the default set is [CryptoUser, KeysManager, KeysImporter, KeysExporter].

A SystemAdmin can add or remove Roles for an existing User. A User with a SystemAdmin or ResourceViewer can always check which Roles are set for a User using /admin/get-user-roles.

A SystemAdmin can also create a User with a custom set of Roles using /admin/create-user-with-custom-roles.

For typical use cases, a sensible configuration may include:

1. One or more SystemAdmin Users for IT / Infra teams.
2. Users with ResourceViewer and PoliciesManager Roles for dev teams.
3. A User with the minimal set of key using Roles (e.g. CryptoUser, KeysImporter, etc.) possible for production machines that perform the actual crypto operations.

Creating a User

API Key (Classic)

To create a User, a SystemAdmin must send a GET request to the /admin/create-user endpoint.

The request may include a name query parameter, which is a human-readable, unique name for the User:

curl -L -X GET 'https://<YOUR_VERTEX>/admin/create-user?name=human-readable-name-for-user' \
-H 'Accept: application/json' \
-H 'Authorization: <ADMIN_TOKEN>'

In response, an API key will be generated for the User and returned to the SystemAdmin, together with a user_id that the SystemAdmin may then use for setting Policies for the User or other administrative operations.

GCP Service Account

To create a User, a SystemAdmin must send a GET request to the /admin/create-user endpoint.

The optional fields authentication_provider and identifier must be included in the request body to specify that the User will authenticate using a GCP service account.

1. authentication_provider must be set to gcp.
2. identifier must be set to the email of the GCP service account that will be used to authenticate the User (e.g. gcp-service-account@example.iam.gserviceaccount.com).

The request may also include a name query parameter, which is a human-readable, unique name for the User:

curl -v -L -X GET 'https://<YOUR_VERTEX>/admin/create-user?name=human-readable-name-for-user' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -d '{"authentication_provider" : "gcp", "identifier" : "gcp-service-account"}'

In response the unique user_id of the user will be returned.

After user creation any request made by the user will happen through identity token issued by GCP.

Fetching the GCP Identity Token:

For example, from a GCP VM, you can obtain the identity token using the following command:

gcloud auth print-identity-token --audiences=<vertex_persistent_keygen_id>

Token Audience

In order to ensure the identity token is valid for the specific Vertex instance, make sure to set the --audiences flag to the Vertex persistent keygen id.

Managing User API Keys

Note

This section is referring to Users which use API keys as authentication methods. An API key operation on a User which has authentication based on a workload identity will result in an error.

• A User can have multiple API Keys, or none at all.
• Every User starts with one API key, which is generated when the User is created.
• An Admin can generate additional API Keys for a User by sending a GET request to the /admin/generate-api-key endpoint.
• An Admin can also revoke an API key by sending a DELETE request to the /admin/revoke-api-key endpoint.
• If a User has no API Keys, the User will not be able to interact with the Vertex but its Keys and data will still be stored by the Vertex and a SystemAdmin will be able to create a new API Key for it to "activate" this User again.

Deleting a User

To delete a User, an Admin must send a DELETE request to the /admin/delete-user endpoint. The delete operation will only succeed if the User has no key shares associated with it. If you are sure you want to delete the User, you should first delete all the Keys associated with the User (using /admin/list-all-user-keys to list them and then delete-key-share to delete them) and then delete the User.

Key Ownership and Permissions

Above we detail the different Roles Users have in the system, now we will explain how different Users can be provided permissions to use Keys.

Key Permissions are introduced to specify which Users have which level of access to a specific Key in the system.

There are two types of Key Permissions:

1. An Admin Key Permission allows the User to perform all available key operations on that specific Key. Users with this permission are known as Key Admins.
2. When a User is assigned the Use Key Permission for a specific key, they can only perform sign and derive-pubkey actions on that key. Users with Use permissions are known as Key Users.

Roles and Key Permission Enforcement

Key Permissions are enforced after User Roles.

This means that when a User calls a specific endpoint (e.g. /sign), first its Roles are checked (e.g. are they a CryptoUser or KeysManager) and then the User's Key Permissions are checked for the specific key that they called the endpoint for (e.g. have they been assigned the Admin or Use permission for this specific Key).

The User that created a Key is automatically assigned the Admin Key Permission to that Key and can perform any action authorized by its Roles.

A SystemAdmin or a KeysManager with the Admin Key Permission for a specific Key can grant Key Permissions to Users using /admin/keys/grant-usage-permission as well as revoke these using /admin/keys/revoke-usage-permission. It can also see all Key Permissions using /admin/keys/get-usage-permissions.

Key Permissions are particularly useful for separating key management responsibilities.

One User can manage a Key's lifecycle (e.g. perform refreshes and reshares), while another User can only sign transactions with that Key.

As an example, an organization assigns Key Permissions to different sets of Users as follows:

1. An operations team that imports sensitive keys into the system, have the Admin Key Permission for the imported keys.
2. A security team responsible for key refresh operations and access management, are assigned an Admin Key Permission as well for those Keys.
3. Production machines that use these Keys to sign transactions, are assigned with a Use permission on those Keys.