Identity

Overview

Identity (also known as a workload identity) is one of the four Control Plane principal types (users, service accounts, groups, and identities). A 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)

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)

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

Native Cloud Network Access

Provides secure, private connectivity from a 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 and can be assigned to multiple workloads 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 can be assigned exactly one identity. An identity is only required when a workload needs to consume cloud resources without embedding credentials and/or when a workload needs to consume resources in a private network such as a VPC. If neither is required, a workload can operate without assigning it an identity. Once configured, an identity assigned to a 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 to specific TCP hosts and ports is facilitated using agents. This capability is referred to as “wormholes”.)
Access the NATS NGS service using scoped credentials automatically supplied at runtime

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.

Create an Identity

Refer to the Create an 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:

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:

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:

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:

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.

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

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:

awsPrivateLink:
  endpointServiceName: "com.amazonaws.vpce.us-east-1.vpce-svc-12345678"

GCP Service Connect Structure:

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:

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:

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

# AWS Identity - reusing existing role
aws:
  cloudAccountLink: "/org/my-org/cloudaccount/aws-prod"
  roleName: "MyExistingRole"

Alternative GCP Identity Example (using existing service account)

# GCP Identity - using existing service account
gcp:
  cloudAccountLink: "/org/my-org/cloudaccount/gcp-prod"
  serviceAccount: "[email protected]"
  scopes:
    - "https://www.googleapis.com/auth/cloud-platform"

Permissions

The permissions below are used to define policies together with one or more of the four principal types:

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.

Documentation

Quickstart

Concepts

Core

Reference

Overview

Cloud Provider Access (Universal Cloud Identity)

Private Network Access (Cloud Wormhole)

Native Cloud Network Access

Create an Identity

Identity Specification

Cloud Provider Access

AWS Identity (`aws`)

GCP Identity (`gcp`)

Azure Identity (`azure`)

NATS Identity (`ngs`)

Private Network Access

Network Resources (`networkResources`)

Native Network Resources (`nativeNetworkResources`)

Status

Additional Fields

Example YAML

Alternative AWS Identity Example (using existing role)

Alternative GCP Identity Example (using existing service account)

Permissions

Access Report

CLI

​Overview

​Cloud Provider Access (Universal Cloud Identity)

​Private Network Access (Cloud Wormhole)

​Native Cloud Network Access

​Create an Identity

​Identity Specification

​Cloud Provider Access

​AWS Identity (aws)

​GCP Identity (gcp)

​Azure Identity (azure)

​NATS Identity (ngs)

​Private Network Access

​Network Resources (networkResources)

​Native Network Resources (nativeNetworkResources)

​Status

​Additional Fields

​Example YAML

​Alternative AWS Identity Example (using existing role)

​Alternative GCP Identity Example (using existing service account)

​Permissions

​Access Report

​CLI

Overview

Cloud Provider Access (Universal Cloud Identity)

Private Network Access (Cloud Wormhole)

Native Cloud Network Access

Create an Identity

Identity Specification

Cloud Provider Access

AWS Identity (`aws`)

GCP Identity (`gcp`)

Azure Identity (`azure`)

NATS Identity (`ngs`)

Private Network Access

Network Resources (`networkResources`)

Native Network Resources (`nativeNetworkResources`)

Status

Additional Fields

Example YAML

Alternative AWS Identity Example (using existing role)

Alternative GCP Identity Example (using existing service account)

Permissions

Access Report

CLI