Authenticate with service identities

Service identities are the accounts that workloads or services use to programmatically consume resources and access microservices securely. They are a special kind of identity used by an application or workload rather than by a person. Similar to a user account, service identities can be granted permissions and roles but they can't sign in like a human user.

Service identities are useful for managing Google Distributed Cloud (GDC) air-gapped infrastructure, such as:

• Internal Distributed Cloud services and workloads to securely access Distributed Cloud control plane application programming interface (API). For example, Database Services interacting with the Kubernetes APIs to create and delete databases.
• Customer workloads in Distributed Cloud to access Distributed Cloud services and make authorized application programming interface (API) calls. For example, service identities can manage a customer using a Vertex AI Workbench notebook to transcribe audio files using the Speech-to-Text API.
• External workloads to federate with Distributed Cloud. For example, service identities can manage an application external to Distributed Cloud that digitizes documents but wants to use the Optical Character Recognition (OCR) API to replace their current OCR engine.
• Distributed Cloud services or system controllers to securely access customer resources or user clusters. For example, service identities can manage authentication and authorization workflows where the service controllers running in admin clusters need to run workloads within the user clusters that are managed by customers.

You can manage service identities by using the GDC console or the gdcloud CLI. With the gdcloud CLI, the service identity feature is built upon the ProjectServiceAccount API.

Before you begin

You can create service identities only within a project. For more information about creating a project, see Create a project.

Create a service identity

To get the permissions required to create service identities, ask your Project IAM Admin to grant you the Project IAM Admin (project-iam-admin) role.

Users with access to service identities can access all service identities within a project.

To create service identities in a project, use the GDC console or the gdcloud CLI.

Console

1. Sign in to the GDC console.
2. In the navigation menu, select Identity & Access > Service identities.
3. Click Create Service Identity. The Service Identity details page opens.
4. In the Service identity name field, enter a name for your service identity. For example: testserviceidentity.
5. Click Create.

gdcloud

Create a service identity:

gdcloud iam service-accounts create NAME \
        --project=PROJECT

Replace the following values:

• NAME: the name of the ProjectServiceAccount. The name must be unique within the project namespace.
• PROJECT: the project to create the service identity in. If gdcloud init is already set, omit the --project flag.

This command creates a ProjectServiceAccount in the project namespace on the org admin cluster.

View service identities

To view a list of service identities in a project, use the GDC console or the gdcloud CLI.

Console

1. Sign in to the GDC console.
2. Select a project.
3. In the navigation menu, click Identity & Access > Service Identities to view the list of service identities for the project.

gdcloud

List the service identities in a project:

gdcloud iam service-accounts list \
    --project=PROJECT

Assign a role binding to the service identity

To assign a role binding, you must have the proper permissions. To get the permissions required to assign roles, ask your Project IAM Admin to grant you the Project IAM Admin (project-iam-admin) role.

Use either the GDC console or the gdcloud CLI to assign a role binding.

Console

1. Sign in to the GDC console.
2. Select a project.
3. In the navigation menu, select Identity & Access > Access.
4. In the Member list, click Add member. You see the Users and roles page.
5. Select Service identity in the Member type list.
6. In the Service identity list, select the service identity you want to assign a role binding.
7. In the Role list, select the role that you want to assign to the service identity, such as Backup Creator.
8. Optional: To add another role, click Add another role. Select the additional role.
9. Click Add.

gdcloud

This command creates and names the project role binding to bind the specified role with the ProjectServiceAccount on the org admin cluster:

gdcloud iam service-accounts add-iam-policy-binding \
    --project=PROJECT \
    --role=ROLE \
    --iam-account=NAME

Replace the following values:

• PROJECT: the project to create the role binding in. If gdcloud init is already set, then you can omit the --project flag.
• ROLE: the predefined role to assign to the ProjectServiceAccount. Specify roles in the format Role/name where Role is the Kubernetes type, such as Roleor ProjectRole, and name is the name of the predefined role. For example, to assign the Project Viewer role, set the role to Role/project-viewer.
• NAME: the name of the service identity to use.

Delete a service identity

To delete service identities in a project, use the GDC console or the gdcloud CLI.

Note: After you delete a service identity, applications don't have access to project resources through that service identity.

Console

1. Sign in to the GDC console.
2. In the navigation menu, select Identity & Access > Service Identities.
3. Select the checkbox of the service identity you want to delete.
4. Click Delete.
5. The confirmation dialog appears. In the Confirm by typing the following below field, enter remove.
6. Click Delete.

gdcloud

Run the following command to delete a service identity:

gdcloud iam service-accounts delete NAME \
    --project=PROJECT

Create and add key pairs

To create and add key pairs in a project, use the GDC console or the gdcloud CLI.

Console

1. Sign in to the GDC console.
2. In the navigation menu, select Identity & Access > Service Identities.
3. Click the name of the service identity you want to add in the key.
4. Click Create New Key.
5. The new key appears in the Keys list, and a dialog confirms you've created the key successfully.

gdcloud

This command creates the application default credentials JSON file and the public and private key pairs:

gdcloud iam service-accounts keys create APPLICATION_DEFAULT_CREDENTIALS_FILENAME \
    --project=PROJECT \
    --iam-account=NAME \
    --ca-cert-path=CA_CERTIFICATE_PATH

Replace the following values:

• APPLICATION_DEFAULT_CREDENTIALS_FILENAME: the name of the JSON file.
• PROJECT : selects the project to create the key for. If gdcloud init is already set, then you can omit the --project flag.
• NAME: the name of the service identity to add the key for.
• CA_CERTIFICATE_PATH: Optional: the certificate authority (CA) certificate path to verify the authentication endpoint. If you do not specify this path, the system CA certificates are used. You must install the CA in the system CA certificates.

Distributed Cloud adds the public key to the ProjectServiceAccount keys you use to verify the JSON web tokens (JWT) the private key signs. The private key is written to the application default credentials JSON file.

The following example shows the application default credentials JSON file:

{
"type": "gdch_service_account",
"format_version": "1",
"project": "project_name",
"private_key_id": "abcdef1234567890",
"private_key": "-----BEGIN RSA PRIVATE KEY-----\nETC\n-----END RSA PRIVATE KEY-----\n",
"name": "service_identity_name",
"ca_cert_path": "service_identity_name",
"token_uri": "https://service-identity.<Domain>/authenticate"
}

This example uses the following values:

• project: the project namespace in the organization.
• private_key_id: the ID assigned to the key.
• private_key: the private key the CLI generates.
• name: the name of the service identity.
• token_uri: the address of the authentication endpoint.

List credentials for service identities

List the public keys from a specific ProjectServiceAccount in the project:

gdcloud iam service-accounts keys list \
    --project=PROJECT \
    --iam-account=NAME

Delete credentials

To delete the public key, use the GDC console or the gdcloud CLI.

Note: Deleting the key does not revoke the short-lived credentials that are issued by using the key.

Console

1. Sign in to the GDC console.
2. In the navigation menu, select Identity & Access > Service Identities.
3. Click the name of the service identity that has the key you want to delete.
4. Click Delete.
5. In the confirmation dialog, click Delete.

gdcloud

Remove the public key with the key ID from the specific ProjectServiceAccount in the project:

gdcloud iam service-accounts keys delete KEY_ID \
    --project=PROJECT \
    --iam-account=NAME