> ## Documentation Index
> Fetch the complete documentation index at: https://docs.controlplane.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Identity

> Workload identities for credential-free cloud provider access via Universal Cloud Identity. Covers AWS, GCP, Azure and network resources.

## Overview

**Identity** (also known as a workload identity) is one of the four Control Plane [principal types](/concepts/access-control) (users, service accounts, groups, and identities).

A [workload](/concepts/workload) needing to consume cloud resources from one or more cloud providers (e.g., AWS, Azure, and GCP) without storing credentials or needing to communicate to endpoints within a private network - must be assigned an **identity**.

An **identity** is a named object that allows an authorized administrator to define:

### [Cloud Provider Access (Universal Cloud Identity)](/reference/identity#cloud-provider-access)

* Least-privilege access rules allowed on cloud resources across cloud providers. Each identity can reference only one cloud account per provider. For example, you can have one account in Azure and one account in GCP, but not two different accounts in GCP within the same identity. You define access policies granted to the identity for each cloud provider you need to use (one, two, or all three clouds, depending on your workload requirements).

### [Private Network Access (Cloud Wormhole)](/reference/identity#network-resources-networkresources)

* Network traversal rules from [workloads](/concepts/workload) into specific endpoints in private networks (e.g., a VPC). These rules connect an [agent](/reference/agent) in a private network to the Control Plane infrastructure, allowing [workloads](/concepts/workload) to selectively access TCP endpoints inside private networks where [agents](/reference/agent) are installed and running.

### [Native Cloud Network Access](/reference/identity#native-network-resources-nativenetworkresources)

* Provides secure, private connectivity from a [workload](/concepts/workload) to cloud-hosted services across AWS (vpc endpoints) and GCP (private service connect) without traversing the public internet. It leverages cloud provider-specific private networking services to route traffic over internal infrastructure. This enables low-latency, secure communication to private resources while maintaining strict network isolation and identity-based access control.

An **identity** is scoped to a [GVC](/reference/gvc) and can be assigned to multiple [workloads](/concepts/workload) within the same GVC that needs the same cloud resources and network access. Identities cannot be shared across GVCs. Different GVCs can have identities with the same name; they are independent resources.

A [workload](/concepts/workload) can be assigned exactly one **identity**. An **identity** is only required when a [workload](/concepts/workload) needs to consume cloud resources without embedding credentials and/or when a [workload](/concepts/workload) needs to consume resources in a private network such as a VPC. If neither is required, a [workload](/concepts/workload) can operate **without** assigning it an **identity**.

Once configured, an **identity** assigned to a [workload](/concepts/workload) enables it to:

* Access specific resources of AWS, Azure, and/or GCP
* Access private network resources from external cloud accounts, data centers or any other private network. (Tunneling network traffic from [workloads](/concepts/workload) to specific TCP hosts and ports is facilitated using [agents](/reference/agent). This capability is referred to as “wormholes”.)
* Access the NATS NGS service using scoped credentials automatically supplied at runtime

<Warning>
  Identities are powerful Control Plane resources that can be granted any permission to your cloud environment. The ability to create identities should only be given to administrators by using a [policy](/reference/policy).
</Warning>

## Create an Identity

Refer to the [Create an Identity](/guides/create-identity) guide for additional details.

## Identity Specification

An identity can be configured with the following fields:

## Cloud Provider Access

### AWS Identity (`aws`)

| Field              | Type   | Required | Description                           |
| ------------------ | ------ | -------- | ------------------------------------- |
| `cloudAccountLink` | string | Yes      | Link to the AWS cloud account         |
| `roleName`         | string | No\*     | AWS role name to reuse (max 64 chars) |
| `policyRefs`       | array  | No\*     | Array of policy references            |
| `trustPolicy`      | object | No       | AWS trust policy document             |

\*Either `roleName` OR `policyRefs` is required, but not both.

**Trust Policy Structure:**

```yaml theme={null}
trustPolicy:
  Version: "2012-10-17"  # Optional, defaults to "2012-10-17"
  Statement:
    - # Policy statement objects
```

### GCP Identity (`gcp`)

| Field              | Type   | Required | Description                                                                     |
| ------------------ | ------ | -------- | ------------------------------------------------------------------------------- |
| `cloudAccountLink` | string | Yes      | Link to the GCP cloud account                                                   |
| `serviceAccount`   | string | No\*     | Existing service account email (must end with `.gserviceaccount.com`)           |
| `bindings`         | array  | No\*     | Array of role bindings                                                          |
| `scopes`           | array  | No       | OAuth scopes (defaults to `["https://www.googleapis.com/auth/cloud-platform"]`) |

\*Either `serviceAccount` OR `bindings` is required, but not both.

**Binding Structure:**

```yaml theme={null}
bindings:
  - resource: "projects/my-project"  # Optional, defaults to project
    roles:
      - "roles/storage.objectViewer"
      - "roles/bigquery.dataViewer"
```

### Azure Identity (`azure`)

| Field              | Type   | Required | Description                     |
| ------------------ | ------ | -------- | ------------------------------- |
| `cloudAccountLink` | string | Yes      | Link to the Azure cloud account |
| `roleAssignments`  | array  | Yes      | Array of role assignments       |

**Role Assignment Structure:**

```yaml theme={null}
roleAssignments:
  - scope: "/subscriptions/123/resourceGroups/my-rg"  # Optional, defaults to subscription
    roles:
      - "Reader"
      - "Storage Blob Data Reader"
```

### NATS Identity (`ngs`)

| Field              | Type   | Required | Description                                              |
| ------------------ | ------ | -------- | -------------------------------------------------------- |
| `cloudAccountLink` | string | Yes      | Link to the NATS cloud account                           |
| `pub`              | object | No       | Publish permissions                                      |
| `sub`              | object | No       | Subscribe permissions                                    |
| `resp`             | object | No       | Response permissions                                     |
| `subs`             | number | No       | Max subscriptions per connection (default: -1, no limit) |
| `data`             | number | No       | Max bytes a connection can send (default: -1, no limit)  |
| `payload`          | number | No       | Max message payload (default: -1, no limit)              |

**Permission Structure:**

```yaml theme={null}
pub:
  allow: ["orders.*", "users.>"]
  deny: ["orders.sensitive.*"]
sub:
  allow: ["orders.*", "users.>"]
  deny: ["orders.sensitive.*"]
resp:
  max: 1  # Number of responses allowed (-1 = no limit)
  ttl: "30s"  # Deadline format: #ms, #s, #m, #h
```

## Private Network Access

### Network Resources (`networkResources`)

| Field        | Type   | Required | Description                             |
| ------------ | ------ | -------- | --------------------------------------- |
| `name`       | string | Yes      | Resource name or domain                 |
| `agentLink`  | string | No       | Link to the agent                       |
| `IPs`        | array  | No\*     | Array of IPv4 addresses (1-5 addresses) |
| `FQDN`       | string | No\*     | Fully qualified domain name             |
| `resolverIP` | string | No       | IPv4 resolver address                   |
| `ports`      | array  | Yes      | Array of ports (1-10 ports, 0-65535)    |

\*Either `IPs` OR `FQDN` is required.

<Note>
  All agents referenced in an identity must be the same protocol version (v1 or v2).
</Note>

### Native Network Resources (`nativeNetworkResources`)

| Field               | Type   | Required | Description                          |
| ------------------- | ------ | -------- | ------------------------------------ |
| `name`              | string | Yes      | Resource name or domain              |
| `FQDN`              | string | No       | Fully qualified domain name          |
| `ports`             | array  | Yes      | Array of ports (1-10 ports, 0-65535) |
| `awsPrivateLink`    | object | No\*     | AWS PrivateLink configuration        |
| `gcpServiceConnect` | object | No\*     | GCP Service Connect configuration    |

\*Either `awsPrivateLink` OR `gcpServiceConnect` is required.

**AWS PrivateLink Structure:**

```yaml theme={null}
awsPrivateLink:
  endpointServiceName: "com.amazonaws.vpce.us-east-1.vpce-svc-12345678"
```

**GCP Service Connect Structure:**

```yaml theme={null}
gcpServiceConnect:
  targetService: "projects/my-project/regions/us-central1/serviceAttachments/my-service"
```

## Status

| Field               | Type   | Required | Description                 |
| ------------------- | ------ | -------- | --------------------------- |
| `status`            | object | No       | Provider status information |
| `status.objectName` | string | No       | Object name                 |
| `status.aws`        | object | No       | AWS provider status         |
| `status.gcp`        | object | No       | GCP provider status         |
| `status.azure`      | object | No       | Azure provider status       |

**Provider Status Structure:**

```yaml theme={null}
status:
  objectName: "my-identity"
  aws:
    lastError: "Error message if any"
    usable: true
  gcp:
    lastError: null
    usable: true
  azure:
    lastError: null
    usable: false
```

## Additional Fields

| Field | Type   | Required | Description                                         |
| ----- | ------ | -------- | --------------------------------------------------- |
| `gvc` | string | No       | Parent GVC (used by local tools, ignored by server) |

## Example YAML

Here's a comprehensive example showing all identity types and configurations:

```yaml theme={null}
# Multi-cloud identity with all provider types
name: "multi-cloud-workload-identity"
description: "Identity for workload accessing AWS, GCP, Azure, and NATS resources"
tags:
  environment: "production"
  team: "platform"

# AWS Identity - using policy references
aws:
  cloudAccountLink: "/org/my-org/cloudaccount/aws-prod"
  policyRefs:
    - "aws::arn:aws:iam::123456789012:policy/S3ReadOnly"
    - "aws::arn:aws:iam::123456789012:policy/DynamoDBReadOnly"
  trustPolicy:
    Version: "2012-10-17"
    Statement:
      - Effect: "Allow"
        Principal:
          Service: "ec2.amazonaws.com"
        Action: "sts:AssumeRole"

# GCP Identity - using role bindings
gcp:
  cloudAccountLink: "/org/my-org/cloudaccount/gcp-prod"
  bindings:
    - resource: "projects/my-gcp-project"
      roles:
        - "roles/storage.objectViewer"
        - "roles/bigquery.dataViewer"
        - "roles/pubsub.subscriber"
  scopes:
    - "https://www.googleapis.com/auth/cloud-platform"
    - "https://www.googleapis.com/auth/bigquery"

# Azure Identity
azure:
  cloudAccountLink: "/org/my-org/cloudaccount/azure-prod"
  roleAssignments:
    - scope: "/subscriptions/12345678-1234-1234-1234-123456789012/resourceGroups/my-rg"
      roles:
        - "Reader"
        - "Storage Blob Data Reader"
    - scope: "/subscriptions/12345678-1234-1234-1234-123456789012"
      roles:
        - "Contributor"

# NATS Identity
ngs:
  cloudAccountLink: "/org/my-org/cloudaccount/nats-prod"
  pub:
    allow: ["orders.*", "users.>", "notifications.*"]
    deny: ["orders.sensitive.*", "users.admin.*"]
  sub:
    allow: ["orders.*", "users.>", "responses.>"]
    deny: ["orders.sensitive.*"]
  resp:
    max: 5
    ttl: "30s"
  subs: 100
  data: 1048576  # 1MB
  payload: 65536  # 64KB

# Network Resources (Cloud Wormhole)
networkResources:
  - name: "database-server"
    agentLink: "/org/my-org/agent/db-agent"
    IPs: ["10.0.1.100", "10.0.1.101"]
    ports: [5432, 3306]
    resolverIP: "10.0.1.1"
  - name: "api-gateway"
    FQDN: "api.internal.company.com"
    ports: [443, 8080]
  - name: "cache-cluster"
    agentLink: "/org/my-org/agent/cache-agent"
    IPs: ["10.0.2.50"]
    ports: [6379, 11211]

# Native Network Resources
nativeNetworkResources:
  - name: "aws-rds-proxy"
    FQDN: "rds-proxy.us-east-1.amazonaws.com"
    ports: [5432]
    awsPrivateLink:
      endpointServiceName: "com.amazonaws.vpce.us-east-1.vpce-svc-12345678abcdef"
  - name: "gcp-cloud-sql"
    FQDN: "my-project:us-central1:my-instance"
    ports: [5432]
    gcpServiceConnect:
      targetService: "projects/my-project/regions/us-central1/serviceAttachments/my-service"

# Status (read-only, set by system)
status:
  objectName: "multi-cloud-workload-identity"
  aws:
    lastError: null
    usable: true
  gcp:
    lastError: null
    usable: true
  azure:
    lastError: "Authentication failed"
    usable: false
```

## Alternative AWS Identity Example (using existing role)

```yaml theme={null}
# AWS Identity - reusing existing role
aws:
  cloudAccountLink: "/org/my-org/cloudaccount/aws-prod"
  roleName: "MyExistingRole"
```

## Alternative GCP Identity Example (using existing service account)

```yaml theme={null}
# GCP Identity - using existing service account
gcp:
  cloudAccountLink: "/org/my-org/cloudaccount/gcp-prod"
  serviceAccount: "my-service-account@my-project.iam.gserviceaccount.com"
  scopes:
    - "https://www.googleapis.com/auth/cloud-platform"
```

## Permissions

The permissions below are used to define [policies](/reference/policy) together with one or more of the four
[principal types](/concepts/access-control):

| Permission | Description                                                | Implies                                 |
| :--------- | :--------------------------------------------------------- | :-------------------------------------- |
| create     | Create new identities                                      |                                         |
| delete     | Delete existing identities                                 |                                         |
| edit       | Modify existing identities                                 | view                                    |
| manage     | Full access                                                | create, delete, edit, manage, use, view |
| use        | Refer to this identity from other entities (workload, etc) | view                                    |
| view       | Read-only access                                           |                                         |

## Access Report

Displays the permissions granted to principals for the identity.

## CLI

To view the CLI documentation for Identities, see the [Identity CLI reference](/cli-reference/commands/identity).