{"slug":"workload-identity-federation","title":"Workload identity federation","tags":["tailscale"],"agent_summary":"Last validated: Jan 30, 2026","trigger_phrases":[],"runnable":false,"markdown":"\r\n# Workload identity federation\r\n\r\nLast validated: Jan 30, 2026\r\n\r\nWorkload identity federation lets cloud-hosted infrastructure in providers like Microsoft Azure, Google Cloud Platform, Amazon Web Services, or GitHub Actions authenticate to a tailnet or the Tailscale API using provider-native identity tokens instead of Tailscale auth keys or OAuth clients. By leveraging the provider's federated OpenID Connect (OIDC) identities, tailnet administrators can streamline credential management and infrastructure automation.\r\n\r\n## [How it works](https://tailscale.com/docs/features/workload-identity-federation\\#how-it-works)\r\n\r\n![A process flow diagram for a standard workload identity federation flow, showing how a cloud workload can exchange a signed JWT from its provider with Tailscale to authenticate itself to the Tailscale API.](https://tailscale.com/_next/image?url=%2F_next%2Fstatic%2Fmedia%2Fwif-process.0c83a2dc.png&w=3840&q=75)\r\n\r\nWhen a cloud workload (such as a CI job, serverless function, or virtual machine) wants to join your tailnet or call the Tailscale API, it first asks its own platform for an OIDC token.\r\n\r\nThe OIDC token is a signed JSON Web Token (JWT) that conveys three assurances from the cloud platform:\r\n\r\n- It vouches for the workload's identity.\r\n- It specifies exactly which workload the JWT represents.\r\n- It declares who is permitted to consume the token.\r\n\r\nBecause the platform signs the token with its publicly advertised keys, anyone can verify the signature and trust that the claims are genuine.\r\n\r\nBefore any exchange can take place, a tailnet admin establishes trust by specifying the OIDC issuer to trust and defining claim-matching rules that map specific workloads, such as a particular GitHub repository, Google Cloud service account, or Azure workload, onto the tags and API scopes they should receive. Tokens that fail to match these rules are rejected automatically.\r\n\r\nThe workload then sends that OIDC token to Tailscale's token exchange endpoint. Behind the scenes, Tailscale fetches the issuer's public keys, validates the signature, standard claims (issuer, audience, expiry), and claim-matching rules and then returns a short-lived API token with the scopes you configured when configuring identity federation in the Tailscale admin console.\r\n\r\nWith this API token, the workload can join or manage the tailnet with the Tailscale API.\r\n\r\n## [Set up a federated identity](https://tailscale.com/docs/features/workload-identity-federation\\#set-up-a-federated-identity)\r\n\r\nBefore a cloud workload can use its signed OIDC token to authenticate to Tailscale, you must set up a federated identity in Tailscale and assign all necessary [scopes](https://tailscale.com/docs/reference/trust-credentials#scopes).\r\n\r\nFederated identities can be configured using:\r\n\r\n- The [admin console](https://tailscale.com/docs/features/workload-identity-federation#configure-federated-identities-in-the-admin-console)\r\n- The [Tailscale Terraform provider](https://tailscale.com/docs/features/workload-identity-federation#configure-federated-identities-using-the-tailscale-terraform-provider)\r\n- [`tailscale-client-go-v2`](https://tailscale.com/docs/features/workload-identity-federation#configure-federated-identities-using-tailscale-client-go-v2)\r\n- The [Tailscale API](https://tailscale.com/docs/features/workload-identity-federation#configure-federated-identities-using-the-tailscale-api)\r\n\r\n### [Configure federated identities in the admin console](https://tailscale.com/docs/features/workload-identity-federation\\#configure-federated-identities-in-the-admin-console)\r\n\r\nTo configure federated identities in the Tailscale admin console:\r\n\r\n1. Open the [Trust credentials](https://login.tailscale.com/admin/settings/trust-credentials) page of the admin console.\r\n2. Select the **Credential** button.\r\n3. Select **OpenID Connect**.\r\n4. Select an **Issuer** from the dropdown. Common cloud providers are included in the dropdown, but any infrastructure provider that supports OIDC for workload identity federation can be used if **Custom issuer** is selected.\r\n1. Enter the **Issuer URL** for the cloud provider's OIDC issuer if using a **Custom issuer**.\r\n5. Enter the **Subject**. This value determines the attributes of the workload that must match to successfully receive a Tailscale API token. Find the syntax of the subject (`sub`) claims for common cloud providers in the [common cloud provider token formats](https://tailscale.com/docs/features/workload-identity-federation#common-cloud-provider-token-formats) section.\r\n6. (Optional) Add additional **Custom claims** to further narrow access. Explore token claims for common cloud providers in the [common cloud provider token formats](https://tailscale.com/docs/features/workload-identity-federation#common-cloud-provider-token-formats) section.\r\n7. Select the relevant read and write scopes from the list and select **Generate credential**.\r\n8. Copy the **Client ID** and **Audience (aud claim)**. These are not secrets and will be visible in the admin console.\r\n\r\n#### [Retrieve the Client ID in the admin console](https://tailscale.com/docs/features/workload-identity-federation\\#retrieve-the-client-id-in-the-admin-console)\r\n\r\nIf you need to copy the **Client ID** at a later point in time, you can visit the admin console.\r\n\r\n1. Open the [Trust credentials](https://login.tailscale.com/admin/settings/trust-credentials) page of the admin console.\r\n\r\n2. Use the **Search** and optionally the **Filters** functionality to find the federated identity you are interested in.\r\n - Searching by `tag` may be useful.\r\n - Setting the **Filters** value to **Client type** and selecting **OIDC** may also be useful.\r\n3. Either select the arrow toggle to expand the row or select the ![ellipsis icon](https://tailscale.com/files/images/icons/fa-ellipsis-h.svg) menu and select **View** or **Edit**.\r\n\r\n4. Select the clipboard icon to copy the **Client ID**.\r\n\r\n\r\n### [Configure federated identities using the Tailscale Terraform provider](https://tailscale.com/docs/features/workload-identity-federation\\#configure-federated-identities-using-the-tailscale-terraform-provider)\r\n\r\nTo configure federated identities using the Tailscale Terraform provider with the `tailscale_federated_identity` resource:\r\n\r\n```hcl\r\nresource \"tailscale_federated_identity\" \"example_federated_identity\" {\r\n description = \"Example federated identity\"\r\n scopes = [\"auth_keys\", \"devices:core\"]\r\n tags = [\"tag:test\"]\r\n issuer = \"https://example.com\"\r\n subject = \"example-sub-*\"\r\n custom_claim_rules = {\r\n repo_name = \"example-repo-name\"\r\n }\r\n}\r\n```\r\n\r\nFor more information, refer to the [Tailscale Terraform provider documentation](https://registry.terraform.io/providers/tailscale/tailscale/latest/docs/resources/federated_identity).\r\n\r\n### [Configure federated identities using tailscale-client-go-v2](https://tailscale.com/docs/features/workload-identity-federation\\#configure-federated-identities-using-tailscale-client-go-v2)\r\n\r\nTo configure federated identities federated identities using `tailscale-client-go-v2`:\r\n\r\n```go\r\npackage main\r\n\r\nimport (\r\n\t\"context\"\r\n\t\"os\"\r\n\r\n\t\"tailscale.com/client/tailscale/v2\"\r\n)\r\n\r\nfunc main() {\r\n\tclient := &tailscale.Client{\r\n\t\t// Client configuration\r\n\t}\r\n\r\n\treq := tailscale.CreateFederatedIdentityRequest {\r\n\t\tDescription: \"Example federated identity\",\r\n\t\tScopes: []string{\"auth_keys\", \"devices:core\"},\r\n\t\tTags: []string{\"tag:test\"},\r\n\t\tSubject: \"example-sub-*\",\r\n\t\tCustomClaimRules: map[string]string{\r\n\t\t\t\"repo_name\": \"example-repo-name\",\r\n\t\t},\r\n\t}\r\n\r\n\tfederatedIdentity, err := client.Keys().CreateFederatedIdentity(context.Background(), req)\r\n}\r\n```\r\n\r\nFor more information, refer to [`tailscale-client-go-v2`](https://github.com/tailscale/tailscale-client-go-v2).\r\n\r\n### [Configure federated identities using the Tailscale API](https://tailscale.com/docs/features/workload-identity-federation\\#configure-federated-identities-using-the-tailscale-api)\r\n\r\nTo configure federated identities using the Tailscale API with the `https://api.tailscale.com/api/v2/tailnet/-/keys` endpoint:\r\n\r\n```shell\r\ncurl -X POST https://api.tailscale.com/api/v2/tailnet/-/keys \\\r\n -H \"Content-Type: application/json\" \\\r\n -d '{\r\n \"keyType\": \"federated\",\r\n \"description\": \"Example federated identity\",\r\n \"scopes\": [\\\r\n \"auth_keys\",\\\r\n \"devices:core\"\\\r\n ],\r\n \"tags\": [\\\r\n \"tag:test\"\\\r\n ],\r\n \"issuer\": \"https://example.com\",\r\n \"subject\": \"example-sub-*\",\r\n \"customClaimRules\": {\r\n \"repo_name\": \"example-repo-name\",\r\n }'\r\n```\r\n\r\nFor more information, refer to [endpoint API](https://tailscale.com/api#tag/keys/post/tailnet/%7Btailnet%7D/keys).\r\n\r\n## [Exchange workload identity tokens with Tailscale](https://tailscale.com/docs/features/workload-identity-federation\\#exchange-workload-identity-tokens-with-tailscale)\r\n\r\nWorkload identity tokens must be exchanged with Tailscale to authenticate and provide a Tailscale access token.\r\n\r\nUsing workload identity token exchange for authentication is supported natively in:\r\n\r\n- The [Tailscale GitHub Action](https://tailscale.com/docs/features/workload-identity-federation#tailscale-github-action)\r\n- The [Tailscale Terraform provider](https://tailscale.com/docs/features/workload-identity-federation#tailscale-terraform-provider)\r\n- [`tailscale-client-go-v2`](https://tailscale.com/docs/features/workload-identity-federation#tailscale-client-go-v2)\r\n- The [Tailscale API](https://tailscale.com/docs/features/workload-identity-federation#token-exchange-api)\r\n\r\nWorkload identity can also be used for [registering new nodes](https://tailscale.com/docs/features/workload-identity-federation#register-new-nodes-using-workload-identity) in your tailnet.\r\n\r\n### [Tailscale GitHub Action](https://tailscale.com/docs/features/workload-identity-federation\\#tailscale-github-action)\r\n\r\nWorkload identity can be used to authenticate the Tailscale GitHub action by using the `oauth-client-id`, `audience`, and `tags` arguments:\r\n\r\n```yaml\r\n- name: Tailscale\r\n uses: tailscale/github-action@v4\r\n with:\r\n oauth-client-id: ${{ secrets.TS_OAUTH_CLIENT_ID }}\r\n audience: ${{ secrets.TS_AUDIENCE }}\r\n tags: tag:ci\r\n```\r\n\r\nWorkload identity federation requires the `id-token: write` [permission setting](https://docs.github.com/en/actions/how-tos/secure-your-work/security-harden-deployments/oidc-in-cloud-providers#adding-permissions-settings) for the workflow:\r\n\r\n```yaml\r\npermissions:\r\n id-token: write # This is required for the tailscale action to request a JWT from GitHub\r\n # Additional required permissions for your workflow\r\n```\r\n\r\nFor more information, refer to [GitHub action](https://github.com/tailscale/github-action).\r\n\r\n### [Tailscale Terraform provider](https://tailscale.com/docs/features/workload-identity-federation\\#tailscale-terraform-provider)\r\n\r\nWorkload identity can be used to authenticate the Tailscale Terraform provider by using the `oauth_client_id` and `id_token` provider arguments:\r\n\r\n```hcl\r\nprovider \"tailscale\" {\r\n oauth_client_id = \"my_client_id\"\r\n identity_token = \"my_identity_token\"\r\n tailnet = \"example.com\"\r\n}\r\n```\r\n\r\nFor more information, refer to [Tailscale Terraform provider](https://registry.terraform.io/providers/tailscale/tailscale/latest).\r\n\r\n### [tailscale-client-go-v2](https://tailscale.com/docs/features/workload-identity-federation\\#tailscale-client-go-v2)\r\n\r\nWorkload identity can be used to authenticate `tailscale-client-go-v2` by supplying a `ClientID` and `IDTokenFunc` to `tailscale.Client`:\r\n\r\n```go\r\npackage main\r\n\r\nimport (\r\n\t\"context\"\r\n\t\"os\"\r\n\r\n\t\"tailscale.com/client/tailscale/v2\"\r\n)\r\n\r\nfunc main() {\r\n\tclient := &tailscale.Client{\r\n\t\tTailnet: os.Getenv(\"TAILSCALE_TAILNET\"),\r\n\t\tAuth: &tailscale.IdentityFederation{\r\n\t\t\tClientID: os.Getenv(\"TAILSCALE_OAUTH_CLIENT_ID\"),\r\n\t\t\tIDTokenFunc: func() (string, error) {\r\n\t\t\t\treturn os.Getenv(\"IDENTITY_TOKEN\"), nil\r\n },\r\n\t\t},\r\n\t}\r\n\r\n\t// Example API call\r\n\tdevices, err := client.Devices().List(context.Background())\r\n}\r\n```\r\n\r\nFor more information, refer to [`tailscale-client-go-v2`](https://github.com/tailscale/tailscale-client-go-v2).\r\n\r\n### [Token exchange API](https://tailscale.com/docs/features/workload-identity-federation\\#token-exchange-api)\r\n\r\nThe Tailscale token exchange endpoint is `https://api.tailscale.com/api/v2/oauth/token-exchange`.\r\n\r\nMake requests to the Tailscale token exchange endpoint when you need a short-lived Tailscale access token:\r\n\r\n```shell\r\ncurl -X POST https://api.tailscale.com/api/v2/oauth/token-exchange \\\r\n -H \"Content-Type: application/x-www-form-urlencoded\" \\\r\n -d \"client_id=\" \\\r\n -d \"jwt=\"\r\n```\r\n\r\n- ``: The client ID generated when you configured a federated identity in the Tailscale admin console.\r\n- ``: The signed OIDC JWT provided to the workload by the cloud provider.\r\n\r\nIf the client ID and JWT are valid and match the configured audience, subject, and custom claim rules, Tailscale will return a short-lived API token to use for authenticating the workload to the Tailscale API.\r\n\r\nIf the short-lived API token expires, you can repeat this step to receive a fresh token.\r\n\r\n### [Debugging token exchange errors](https://tailscale.com/docs/features/workload-identity-federation\\#debugging-token-exchange-errors)\r\n\r\nThe latest token exchange error details for a federated identity can be found in the admin console.\r\n\r\n1. Open the [Trust credentials](https://login.tailscale.com/admin/settings/trust-credentials) page of the admin console.\r\n\r\n2. Use the **Search** and optionally the **Filters** functionality to find the federated identity you are interested in.\r\n - Searching by `tag` may be useful.\r\n - Setting the **Filters** value to **Client type** and selecting **OIDC** may also be useful.\r\n3. Select the ![ellipsis icon](https://tailscale.com/files/images/icons/fa-ellipsis-h.svg) menu and select **View** or **Edit**.\r\n\r\n\r\nInformation about the error will be present on this page, with specific guidance varying depending on the type of error.\r\n\r\nErrors will only be cleared once a token exchange has succeeded for the federated identity.\r\n\r\n#### [API error responses](https://tailscale.com/docs/features/workload-identity-federation\\#api-error-responses)\r\n\r\nErrors returned from the token exchange API endpoint will not have specific debugging information directly in the error message.\r\n\r\nThis is done to prevent leaking information to potential bad actors as they could otherwise attempt to reverse engineer your federated identity's configuration from error messages if they know its client ID.\r\n\r\nError messages will instead contain a direct link to the federated identity within the admin console in a message of the form:\r\n\r\n```json\r\n{ \"message\": \"Unauthorized. Visit [link to admin console] for details\" }\r\n```\r\n\r\nInformation about the error will be present on this page, with specific guidance varying depending on the type of error.\r\n\r\nErrors will only be cleared once a token exchange has succeeded for the federated identity.\r\n\r\n## [Register new nodes using workload identity](https://tailscale.com/docs/features/workload-identity-federation\\#register-new-nodes-using-workload-identity)\r\n\r\nA device must run Tailscale v1.90.1 or later to have the `--client-id` and `--id-token` flags.\r\n\r\nYou can use a client ID and OIDC token directly in [`tailscale up`](https://tailscale.com/docs/reference/tailscale-cli/up) to register a new node:\r\n\r\n```shell\r\ntailscale up --client-id=${CLIENT_ID} --id-token=${IDENTITY_TOKEN} --advertise-tags=tag:ci\r\n```\r\n\r\nThe `tailscale up` command expects the `client-id` to be the Client ID used to generate auth keys with workload identity federation. Access the admin console to [retrieve the **Client ID**](https://tailscale.com/docs/features/workload-identity-federation#retrieve-the-client-id-in-the-admin-console).\r\n\r\nThe command also expects the `id-token` to be the ID token from the identity provider to exchange with the control server for workload federation. This value is the signed OIDC JWT and not a short-lived API token.\r\n\r\nThe workload identity credential must have the `auth_keys` scope and the [tags](https://tailscale.com/docs/features/tags) passed to `--advertise-tags` must match the tags you selected when you [configured the federated identity](https://tailscale.com/docs/features/workload-identity-federation#set-up-a-federated-identity).\r\n\r\nThe `--client-id` flag can accept additional URL-style parameters:\r\n\r\n```shell\r\ntailscale up --client-id='${CLIENT_ID}?ephemeral=false&preauthorized=true' --id-token=${IDENTITY_TOKEN} --advertise-tags=tag:ci\r\n```\r\n\r\nThe available parameters are:\r\n\r\n- `ephemeral`: register as an [ephemeral node](https://tailscale.com/docs/features/ephemeral-nodes) (defaults to `true`)\r\n- `preauthorized`: skip manual [device approval](https://tailscale.com/docs/features/access-control/device-management/device-approval) (defaults to `false`)\r\n\r\n### [Automatic cloud token discovery and exchange](https://tailscale.com/docs/features/workload-identity-federation\\#automatic-cloud-token-discovery-and-exchange)\r\n\r\nA device must run Tailscale v1.94.0 or later to have the `--audience` flag.\r\n\r\nTailscale can automatically detect certain cloud and CI environments and retrieve a native identity token from the platform it is running on. When enabled, the client uses this token to authenticate the node to your tailnet using **workload identity federation** without requiring you to manually provision or manage credentials.\r\n\r\nThis functionality is intended for **non-interactive workloads**, such as cloud VMs, containerized services, and CI/CD pipelines, where identity should be derived from the execution environment itself.\r\n\r\nNo long-lived credentials, access keys, or secrets are stored on disk or injected at runtime.\r\n\r\nThis behavior is enabled by passing a client ID and audience to [`tailscale up`](https://tailscale.com/docs/reference/tailscale-cli/up):\r\n\r\n```shell\r\ntailscale up --client-id=${CLIENT_ID} --audience=${AUDIENCE} --advertise-tags=tag:ci\r\n```\r\n\r\nThe command expects `audience` to be the audience specified in the trust configuration for the federated identity referred to by `client-id`.\r\n\r\n#### [Supported environments](https://tailscale.com/docs/features/workload-identity-federation\\#supported-environments)\r\n\r\nAutomatic token discovery requires both a native workload identity on the platform and a matching [trust configuration](https://tailscale.com/docs/features/workload-identity-federation#set-up-a-federated-identity) in Tailscale. Once configured, the Tailscale client will obtain a provider token on your behalf on the platforms described below.\r\n\r\n**AWS**\r\n\r\n**Workload environment**\r\n\r\n- The workload runs on an AWS service that supports IAM roles. For example, Elastic Cloud Compute (EC2), Elastic Container Service (ECS), or Elastic Kubernetes Service (EKS).\r\n- An IAM role is attached to the instance, task, or pod.\r\n\r\n**IAM configuration**\r\n\r\n- The IAM role must allow issuance of web identity tokens from AWS Security Token Service (STS).\r\n- The role's trust policy must permit the configured web identity provider.\r\n\r\n```yaml\r\n{\r\n\"Version\": \"2012-10-17\",\r\n \"Statement\": [\\\r\n {\\\r\n \"Sid\": \"AllowGetWebIdentityTokenForTailscale\",\\\r\n \"Effect\": \"Allow\",\\\r\n \"Action\": \"sts:GetWebIdentityToken\",\\\r\n \"Resource\": \"*\",\\\r\n \"Condition\": {\\\r\n \"ForAnyValue:StringEquals\": {\\\r\n \"sts:IdentityTokenAudience\": \"{YOUR_TAILSCALE_AUDIENCE}\"\\\r\n },\\\r\n \"NumericLessThanEquals\": {\\\r\n \"sts:DurationSeconds\": \"300\"\\\r\n }\\\r\n }\\\r\n }\\\r\n ]\r\n}\r\n```\r\n\r\n**Tailscale configuration**\r\n\r\n- A workload identity federation configuration exists in Tailscale that:\r\n - Trusts the AWS token issuer.\r\n - Expects the correct audience (`aud`).\r\n - Matches any required role or environment-specific claims.\r\n\r\n**Google Cloud**\r\n\r\n**Workload environment**\r\n\r\n- The workload runs on a Google Cloud Platform (GCP) service that exposes the metadata server. For example, Google Compute Engine (GCE) or Google Kubernetes Engine (GKE).\r\n- A **service account** is attached to the VM or workload.\r\n\r\n**IAM configuration**\r\n\r\n- The service account must be allowed to mint identity tokens.\r\n- The workload must be permitted to request identity tokens for the configured audience.\r\n\r\n**Tailscale configuration**\r\n\r\n- A workload identity federation configuration exists in Tailscale that:\r\n - Trusts the GCP token issuer.\r\n - Expects the configured audience.\r\n - Optionally matches service account–specific claims.\r\n\r\n**GitHub Actions**\r\n\r\n**Workflow configuration**\r\n\r\n- The workflow runs on a GitHub-hosted or self-hosted runner that supports OIDC.\r\n- The workflow explicitly enables OIDC token issuance:\r\n\r\n```yaml\r\npermissions:\r\n id-token: write\r\n```\r\n\r\n**Repository or organization configuration**\r\n\r\n- OIDC token issuance is enabled for the repository or organization.\r\n- Any branch, environment, or repository restrictions align with the expected token claims.\r\n\r\n**Tailscale configuration**\r\n\r\n- A workload identity federation configuration exists in Tailscale that:\r\n - Trusts the GitHub Actions OIDC issuer.\r\n - Matches the expected audience, repository, and workflow claims.\r\n\r\n**Unsupported environments**\r\n\r\nIf the client does not detect a supported platform, automatic token discovery is skipped and the client falls back to manual workload identity federation configuration.\r\n\r\n## [Reference](https://tailscale.com/docs/features/workload-identity-federation\\#reference)\r\n\r\nThe following sections provide technical details about claims.\r\n\r\n### [Common cloud provider token formats](https://tailscale.com/docs/features/workload-identity-federation\\#common-cloud-provider-token-formats)\r\n\r\nCloud providers have unique formats for the `sub` claim, and the custom claims, for OIDC tokens that they issue.\r\nBelow are some common cloud providers and the formats of their OIDC tokens.\r\n\r\n[AWS](https://tailscale.com/docs/features/workload-identity-federation?tab=aws) [GitHub Actions](https://tailscale.com/docs/features/workload-identity-federation?tab=github+actions) [Google Cloud](https://tailscale.com/docs/features/workload-identity-federation?tab=google+cloud) [Microsoft Azure](https://tailscale.com/docs/features/workload-identity-federation?tab=microsoft+azure)\r\n\r\n##### [Subject format](https://tailscale.com/docs/features/workload-identity-federation\\#subject-format)\r\n\r\nThe ARN of the IAM principal that requested the token. Refer to [AWS token claims](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_outbound_token_claims.html).\r\n\r\n##### [Token Claims](https://tailscale.com/docs/features/workload-identity-federation\\#token-claims)\r\n\r\nRefer to [AWS token claims](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_outbound_token_claims.html).\r\n\r\n### [Claim value format](https://tailscale.com/docs/features/workload-identity-federation\\#claim-value-format)\r\n\r\nValues specified for the **subject** and **custom claims** are matched against claims values in the OIDC JWT.\r\n\r\nValues can contain an `*` to match against any character. Other characters specified must directly match the value of the claim.\r\n\r\nFor example, specifying `my-example-sub/*` for the subject will successfully match `sub` claims that start with `my-example-sub/`.\r\n\r\n### [Custom claim key format](https://tailscale.com/docs/features/workload-identity-federation\\#custom-claim-key-format)\r\n\r\nKeys for **custom claims** specify the claim in the OIDC JWT to match against.\r\n\r\nFor example, given a token of the form:\r\n\r\n```json\r\n{\r\n\t\"sub\": \"123456-example\",\r\n\t\"iss\": \"https://example.com\",\r\n\t\"aud\": \"api.tailscale.com/12345-67890\",\r\n\t\"user\": \"example\"\r\n}\r\n```\r\n\r\nthe `user` claim can be referenced by specifying `user` for the key.\r\n\r\n#### [Nested claims](https://tailscale.com/docs/features/workload-identity-federation\\#nested-claims)\r\n\r\nKeys can refer to nested claims within a JWT by separating the nested key names with a period.\r\n\r\nFor example, given token of the form:\r\n\r\n```json\r\n{\r\n\t\"sub\": \"123456-example\",\r\n\t\"iss\": \"https://example.com\",\r\n\t\"aud\": \"api.tailscale.com/12345-67890\",\r\n\t\"user\": \"example\",\r\n\t\"user\": {\r\n\t\t\"name\": \"foobar\"\r\n\t}\r\n}\r\n```\r\n\r\nthe nested `name` claim can be referenced by specifying `user.name` for the key.\r\n\r\n#### [Escaping claim names](https://tailscale.com/docs/features/workload-identity-federation\\#escaping-claim-names)\r\n\r\nKeys that contain a period in their name can be escaped by surrounding them in double quotes.\r\n\r\nFor example, given a token of the form:\r\n\r\n```json\r\n{\r\n\t\"sub\": \"123456-example\",\r\n\t\"iss\": \"https://example.com\",\r\n\t\"aud\": \"api.tailscale.com/12345-67890\",\r\n\t\"user\": \"example\",\r\n\t\"open.id\": {\r\n\t\t\"username\": \"foobar\"\r\n\t}\r\n}\r\n```\r\n\r\nthe `open.id` key can be referenced as `\"open.id\"` and the nested `username` key as `\"open.id\".username`.\r\n\r\n### [Generated audience format](https://tailscale.com/docs/features/workload-identity-federation\\#generated-audience-format)\r\n\r\nAudience values generated by Tailscale are of the form: `api.tailscale.com/`.\r\n\r\nFor example, a federated identity with the client ID `Tz8TefihCR11EXAMPLE-kZDRvszg8621EXAMPLE` will have a generated audience of `api.tailscale.com/Tz8TefihCR11EXAMPLE-kZDRvszg8621EXAMPLE`\r\n\r\n## [Limitations](https://tailscale.com/docs/features/workload-identity-federation\\#limitations)\r\n\r\n- The issuer that provides signed JSON Web Tokens (JWTs) to your workloads must be publicly accessible.\r\n\r\n![Project Logo](https://cdn.brandfetch.io/tailscale.com/fallback/lettermark/theme/dark/h/256/w/256/icon?c=1bfwsmEH20zzEfSNTed)\r\n\r\nAsk AI\r\n\r\nreCAPTCHA\r\n\r\nRecaptcha requires verification.\r\n\r\nprotected by **reCAPTCHA**\r\n","html":"

Workload identity federation

\n

Last validated: Jan 30, 2026

\n

Workload identity federation lets cloud-hosted infrastructure in providers like Microsoft Azure, Google Cloud Platform, Amazon Web Services, or GitHub Actions authenticate to a tailnet or the Tailscale API using provider-native identity tokens instead of Tailscale auth keys or OAuth clients. By leveraging the provider's federated OpenID Connect (OIDC) identities, tailnet administrators can streamline credential management and infrastructure automation.

\n

How it works

\n

\"A

\n

When a cloud workload (such as a CI job, serverless function, or virtual machine) wants to join your tailnet or call the Tailscale API, it first asks its own platform for an OIDC token.

\n

The OIDC token is a signed JSON Web Token (JWT) that conveys three assurances from the cloud platform:

\n
    \n
  • It vouches for the workload's identity.
    • \n
  • It specifies exactly which workload the JWT represents.
    • \n
  • It declares who is permitted to consume the token.
    • \n
\n

Because the platform signs the token with its publicly advertised keys, anyone can verify the signature and trust that the claims are genuine.

\n

Before any exchange can take place, a tailnet admin establishes trust by specifying the OIDC issuer to trust and defining claim-matching rules that map specific workloads, such as a particular GitHub repository, Google Cloud service account, or Azure workload, onto the tags and API scopes they should receive. Tokens that fail to match these rules are rejected automatically.

\n

The workload then sends that OIDC token to Tailscale's token exchange endpoint. Behind the scenes, Tailscale fetches the issuer's public keys, validates the signature, standard claims (issuer, audience, expiry), and claim-matching rules and then returns a short-lived API token with the scopes you configured when configuring identity federation in the Tailscale admin console.

\n

With this API token, the workload can join or manage the tailnet with the Tailscale API.

\n

Set up a federated identity

\n

Before a cloud workload can use its signed OIDC token to authenticate to Tailscale, you must set up a federated identity in Tailscale and assign all necessary scopes.

\n

Federated identities can be configured using:

\n\n

Configure federated identities in the admin console

\n

To configure federated identities in the Tailscale admin console:

\n
    \n
  1. Open the Trust credentials page of the admin console.
    2. \n
  2. Select the Credential button.
    3. \n
  3. Select OpenID Connect.
    4. \n
  4. Select an Issuer from the dropdown. Common cloud providers are included in the dropdown, but any infrastructure provider that supports OIDC for workload identity federation can be used if Custom issuer is selected.
    5. \n
  5. Enter the Issuer URL for the cloud provider's OIDC issuer if using a Custom issuer.
    6. \n
  6. Enter the Subject. This value determines the attributes of the workload that must match to successfully receive a Tailscale API token. Find the syntax of the subject (sub) claims for common cloud providers in the common cloud provider token formats section.
    7. \n
  7. (Optional) Add additional Custom claims to further narrow access. Explore token claims for common cloud providers in the common cloud provider token formats section.
    8. \n
  8. Select the relevant read and write scopes from the list and select Generate credential.
    9. \n
  9. Copy the Client ID and Audience (aud claim). These are not secrets and will be visible in the admin console.
    10. \n
\n

Retrieve the Client ID in the admin console

\n

If you need to copy the Client ID at a later point in time, you can visit the admin console.

\n
    \n
  1. \n

    Open the Trust credentials page of the admin console.

    \n
    2. \n
  2. \n

    Use the Search and optionally the Filters functionality to find the federated identity you are interested in.

    \n
      \n
    • Searching by tag may be useful.
      • \n
    • Setting the Filters value to Client type and selecting OIDC may also be useful.
      • \n
    \n
    3. \n
  3. \n

    Either select the arrow toggle to expand the row or select the \"ellipsis menu and select View or Edit.

    \n
    4. \n
  4. \n

    Select the clipboard icon to copy the Client ID.

    \n
    5. \n
\n

Configure federated identities using the Tailscale Terraform provider

\n

To configure federated identities using the Tailscale Terraform provider with the tailscale_federated_identity resource:

\n
resource \"tailscale_federated_identity\" \"example_federated_identity\" {\r\n  description = \"Example federated identity\"\r\n  scopes      = [\"auth_keys\", \"devices:core\"]\r\n  tags        = [\"tag:test\"]\r\n  issuer      = \"https://example.com\"\r\n  subject     = \"example-sub-*\"\r\n  custom_claim_rules = {\r\n    repo_name = \"example-repo-name\"\r\n  }\r\n}\n
\n

For more information, refer to the Tailscale Terraform provider documentation.

\n

Configure federated identities using tailscale-client-go-v2

\n

To configure federated identities federated identities using tailscale-client-go-v2:

\n
package main\r\n\r\nimport (\r\n\t\"context\"\r\n\t\"os\"\r\n\r\n\t\"tailscale.com/client/tailscale/v2\"\r\n)\r\n\r\nfunc main() {\r\n\tclient := &tailscale.Client{\r\n\t\t// Client configuration\r\n\t}\r\n\r\n\treq := tailscale.CreateFederatedIdentityRequest {\r\n\t\tDescription: \"Example federated identity\",\r\n\t\tScopes:  []string{\"auth_keys\", \"devices:core\"},\r\n\t\tTags:    []string{\"tag:test\"},\r\n\t\tSubject: \"example-sub-*\",\r\n\t\tCustomClaimRules: map[string]string{\r\n\t\t\t\"repo_name\": \"example-repo-name\",\r\n\t\t},\r\n\t}\r\n\r\n\tfederatedIdentity, err := client.Keys().CreateFederatedIdentity(context.Background(), req)\r\n}\n
\n

For more information, refer to tailscale-client-go-v2.

\n

Configure federated identities using the Tailscale API

\n

To configure federated identities using the Tailscale API with the https://api.tailscale.com/api/v2/tailnet/-/keys endpoint:

\n
curl -X POST https://api.tailscale.com/api/v2/tailnet/-/keys \\\r\n  -H \"Content-Type: application/json\" \\\r\n  -d   '{\r\n  \"keyType\": \"federated\",\r\n  \"description\": \"Example federated identity\",\r\n  \"scopes\": [\\\r\n    \"auth_keys\",\\\r\n    \"devices:core\"\\\r\n  ],\r\n  \"tags\": [\\\r\n    \"tag:test\"\\\r\n  ],\r\n  \"issuer\": \"https://example.com\",\r\n  \"subject\": \"example-sub-*\",\r\n  \"customClaimRules\": {\r\n    \"repo_name\": \"example-repo-name\",\r\n  }'\n
\n

For more information, refer to endpoint API.

\n

Exchange workload identity tokens with Tailscale

\n

Workload identity tokens must be exchanged with Tailscale to authenticate and provide a Tailscale access token.

\n

Using workload identity token exchange for authentication is supported natively in:

\n\n

Workload identity can also be used for registering new nodes in your tailnet.

\n

Tailscale GitHub Action

\n

Workload identity can be used to authenticate the Tailscale GitHub action by using the oauth-client-id, audience, and tags arguments:

\n
- name: Tailscale\r\n  uses: tailscale/github-action@v4\r\n  with:\r\n    oauth-client-id: ${{ secrets.TS_OAUTH_CLIENT_ID }}\r\n    audience: ${{ secrets.TS_AUDIENCE }}\r\n    tags: tag:ci\n
\n

Workload identity federation requires the id-token: write permission setting for the workflow:

\n
permissions:\r\n  id-token: write # This is required for the tailscale action to request a JWT from GitHub\r\n  # Additional required permissions for your workflow\n
\n

For more information, refer to GitHub action.

\n

Tailscale Terraform provider

\n

Workload identity can be used to authenticate the Tailscale Terraform provider by using the oauth_client_id and id_token provider arguments:

\n
provider \"tailscale\" {\r\n  oauth_client_id = \"my_client_id\"\r\n  identity_token  = \"my_identity_token\"\r\n  tailnet         = \"example.com\"\r\n}\n
\n

For more information, refer to Tailscale Terraform provider.

\n

tailscale-client-go-v2

\n

Workload identity can be used to authenticate tailscale-client-go-v2 by supplying a ClientID and IDTokenFunc to tailscale.Client:

\n
package main\r\n\r\nimport (\r\n\t\"context\"\r\n\t\"os\"\r\n\r\n\t\"tailscale.com/client/tailscale/v2\"\r\n)\r\n\r\nfunc main() {\r\n\tclient := &tailscale.Client{\r\n\t\tTailnet: os.Getenv(\"TAILSCALE_TAILNET\"),\r\n\t\tAuth: &tailscale.IdentityFederation{\r\n\t\t\tClientID: os.Getenv(\"TAILSCALE_OAUTH_CLIENT_ID\"),\r\n\t\t\tIDTokenFunc: func() (string, error) {\r\n\t\t\t\treturn os.Getenv(\"IDENTITY_TOKEN\"), nil\r\n            },\r\n\t\t},\r\n\t}\r\n\r\n\t// Example API call\r\n\tdevices, err := client.Devices().List(context.Background())\r\n}\n
\n

For more information, refer to tailscale-client-go-v2.

\n

Token exchange API

\n

The Tailscale token exchange endpoint is https://api.tailscale.com/api/v2/oauth/token-exchange.

\n

Make requests to the Tailscale token exchange endpoint when you need a short-lived Tailscale access token:

\n
curl -X POST https://api.tailscale.com/api/v2/oauth/token-exchange \\\r\n  -H \"Content-Type: application/x-www-form-urlencoded\" \\\r\n  -d \"client_id=<CLIENT_ID>\" \\\r\n  -d \"jwt=<JWT>\"\n
\n
    \n
  • <CLIENT_ID>: The client ID generated when you configured a federated identity in the Tailscale admin console.
    • \n
  • <JWT>: The signed OIDC JWT provided to the workload by the cloud provider.
    • \n
\n

If the client ID and JWT are valid and match the configured audience, subject, and custom claim rules, Tailscale will return a short-lived API token to use for authenticating the workload to the Tailscale API.

\n

If the short-lived API token expires, you can repeat this step to receive a fresh token.

\n

Debugging token exchange errors

\n

The latest token exchange error details for a federated identity can be found in the admin console.

\n
    \n
  1. \n

    Open the Trust credentials page of the admin console.

    \n
    2. \n
  2. \n

    Use the Search and optionally the Filters functionality to find the federated identity you are interested in.

    \n
      \n
    • Searching by tag may be useful.
      • \n
    • Setting the Filters value to Client type and selecting OIDC may also be useful.
      • \n
    \n
    3. \n
  3. \n

    Select the \"ellipsis menu and select View or Edit.

    \n
    4. \n
\n

Information about the error will be present on this page, with specific guidance varying depending on the type of error.

\n

Errors will only be cleared once a token exchange has succeeded for the federated identity.

\n

API error responses

\n

Errors returned from the token exchange API endpoint will not have specific debugging information directly in the error message.

\n

This is done to prevent leaking information to potential bad actors as they could otherwise attempt to reverse engineer your federated identity's configuration from error messages if they know its client ID.

\n

Error messages will instead contain a direct link to the federated identity within the admin console in a message of the form:

\n
{ \"message\": \"Unauthorized. Visit [link to admin console] for details\" }\n
\n

Information about the error will be present on this page, with specific guidance varying depending on the type of error.

\n

Errors will only be cleared once a token exchange has succeeded for the federated identity.

\n

Register new nodes using workload identity

\n

A device must run Tailscale v1.90.1 or later to have the --client-id and --id-token flags.

\n

You can use a client ID and OIDC token directly in tailscale up to register a new node:

\n
tailscale up --client-id=${CLIENT_ID} --id-token=${IDENTITY_TOKEN} --advertise-tags=tag:ci\n
\n

The tailscale up command expects the client-id to be the Client ID used to generate auth keys with workload identity federation. Access the admin console to retrieve the Client ID.

\n

The command also expects the id-token to be the ID token from the identity provider to exchange with the control server for workload federation. This value is the signed OIDC JWT and not a short-lived API token.

\n

The workload identity credential must have the auth_keys scope and the tags passed to --advertise-tags must match the tags you selected when you configured the federated identity.

\n

The --client-id flag can accept additional URL-style parameters:

\n
tailscale up --client-id='${CLIENT_ID}?ephemeral=false&preauthorized=true' --id-token=${IDENTITY_TOKEN} --advertise-tags=tag:ci\n
\n

The available parameters are:

\n\n

Automatic cloud token discovery and exchange

\n

A device must run Tailscale v1.94.0 or later to have the --audience flag.

\n

Tailscale can automatically detect certain cloud and CI environments and retrieve a native identity token from the platform it is running on. When enabled, the client uses this token to authenticate the node to your tailnet using workload identity federation without requiring you to manually provision or manage credentials.

\n

This functionality is intended for non-interactive workloads, such as cloud VMs, containerized services, and CI/CD pipelines, where identity should be derived from the execution environment itself.

\n

No long-lived credentials, access keys, or secrets are stored on disk or injected at runtime.

\n

This behavior is enabled by passing a client ID and audience to tailscale up:

\n
tailscale up --client-id=${CLIENT_ID} --audience=${AUDIENCE} --advertise-tags=tag:ci\n
\n

The command expects audience to be the audience specified in the trust configuration for the federated identity referred to by client-id.

\n

Supported environments

\n

Automatic token discovery requires both a native workload identity on the platform and a matching trust configuration in Tailscale. Once configured, the Tailscale client will obtain a provider token on your behalf on the platforms described below.

\n

AWS

\n

Workload environment

\n
    \n
  • The workload runs on an AWS service that supports IAM roles. For example, Elastic Cloud Compute (EC2), Elastic Container Service (ECS), or Elastic Kubernetes Service (EKS).
    • \n
  • An IAM role is attached to the instance, task, or pod.
    • \n
\n

IAM configuration

\n
    \n
  • The IAM role must allow issuance of web identity tokens from AWS Security Token Service (STS).
    • \n
  • The role's trust policy must permit the configured web identity provider.
    • \n
\n
{\r\n\"Version\": \"2012-10-17\",\r\n  \"Statement\": [\\\r\n  {\\\r\n    \"Sid\": \"AllowGetWebIdentityTokenForTailscale\",\\\r\n    \"Effect\": \"Allow\",\\\r\n    \"Action\": \"sts:GetWebIdentityToken\",\\\r\n    \"Resource\": \"*\",\\\r\n    \"Condition\": {\\\r\n      \"ForAnyValue:StringEquals\": {\\\r\n        \"sts:IdentityTokenAudience\": \"{YOUR_TAILSCALE_AUDIENCE}\"\\\r\n      },\\\r\n      \"NumericLessThanEquals\": {\\\r\n        \"sts:DurationSeconds\": \"300\"\\\r\n      }\\\r\n    }\\\r\n  }\\\r\n  ]\r\n}\n
\n

Tailscale configuration

\n
    \n
  • A workload identity federation configuration exists in Tailscale that:\n
      \n
    • Trusts the AWS token issuer.
      • \n
    • Expects the correct audience (aud).
      • \n
    • Matches any required role or environment-specific claims.
      • \n
    \n
    • \n
\n

Google Cloud

\n

Workload environment

\n
    \n
  • The workload runs on a Google Cloud Platform (GCP) service that exposes the metadata server. For example, Google Compute Engine (GCE) or Google Kubernetes Engine (GKE).
    • \n
  • A service account is attached to the VM or workload.
    • \n
\n

IAM configuration

\n
    \n
  • The service account must be allowed to mint identity tokens.
    • \n
  • The workload must be permitted to request identity tokens for the configured audience.
    • \n
\n

Tailscale configuration

\n
    \n
  • A workload identity federation configuration exists in Tailscale that:\n
      \n
    • Trusts the GCP token issuer.
      • \n
    • Expects the configured audience.
      • \n
    • Optionally matches service account–specific claims.
      • \n
    \n
    • \n
\n

GitHub Actions

\n

Workflow configuration

\n
    \n
  • The workflow runs on a GitHub-hosted or self-hosted runner that supports OIDC.
    • \n
  • The workflow explicitly enables OIDC token issuance:
    • \n
\n
permissions:\r\n  id-token: write\n
\n

Repository or organization configuration

\n
    \n
  • OIDC token issuance is enabled for the repository or organization.
    • \n
  • Any branch, environment, or repository restrictions align with the expected token claims.
    • \n
\n

Tailscale configuration

\n
    \n
  • A workload identity federation configuration exists in Tailscale that:\n
      \n
    • Trusts the GitHub Actions OIDC issuer.
      • \n
    • Matches the expected audience, repository, and workflow claims.
      • \n
    \n
    • \n
\n

Unsupported environments

\n

If the client does not detect a supported platform, automatic token discovery is skipped and the client falls back to manual workload identity federation configuration.

\n

Reference

\n

The following sections provide technical details about claims.

\n

Common cloud provider token formats

\n

Cloud providers have unique formats for the sub claim, and the custom claims, for OIDC tokens that they issue.\r\nBelow are some common cloud providers and the formats of their OIDC tokens.

\n

AWS GitHub Actions Google Cloud Microsoft Azure

\n
Subject format
\n

The ARN of the IAM principal that requested the token. Refer to AWS token claims.

\n
Token Claims
\n

Refer to AWS token claims.

\n

Claim value format

\n

Values specified for the subject and custom claims are matched against claims values in the OIDC JWT.

\n

Values can contain an * to match against any character. Other characters specified must directly match the value of the claim.

\n

For example, specifying my-example-sub/* for the subject will successfully match sub claims that start with my-example-sub/.

\n

Custom claim key format

\n

Keys for custom claims specify the claim in the OIDC JWT to match against.

\n

For example, given a token of the form:

\n
{\r\n\t\"sub\": \"123456-example\",\r\n\t\"iss\": \"https://example.com\",\r\n\t\"aud\": \"api.tailscale.com/12345-67890\",\r\n\t\"user\": \"example\"\r\n}\n
\n

the user claim can be referenced by specifying user for the key.

\n

Nested claims

\n

Keys can refer to nested claims within a JWT by separating the nested key names with a period.

\n

For example, given token of the form:

\n
{\r\n\t\"sub\": \"123456-example\",\r\n\t\"iss\": \"https://example.com\",\r\n\t\"aud\": \"api.tailscale.com/12345-67890\",\r\n\t\"user\": \"example\",\r\n\t\"user\": {\r\n\t\t\"name\": \"foobar\"\r\n\t}\r\n}\n
\n

the nested name claim can be referenced by specifying user.name for the key.

\n

Escaping claim names

\n

Keys that contain a period in their name can be escaped by surrounding them in double quotes.

\n

For example, given a token of the form:

\n
{\r\n\t\"sub\": \"123456-example\",\r\n\t\"iss\": \"https://example.com\",\r\n\t\"aud\": \"api.tailscale.com/12345-67890\",\r\n\t\"user\": \"example\",\r\n\t\"open.id\": {\r\n\t\t\"username\": \"foobar\"\r\n\t}\r\n}\n
\n

the open.id key can be referenced as \"open.id\" and the nested username key as \"open.id\".username.

\n

Generated audience format

\n

Audience values generated by Tailscale are of the form: api.tailscale.com/<client ID>.

\n

For example, a federated identity with the client ID Tz8TefihCR11EXAMPLE-kZDRvszg8621EXAMPLE will have a generated audience of api.tailscale.com/Tz8TefihCR11EXAMPLE-kZDRvszg8621EXAMPLE

\n

Limitations

\n
    \n
  • The issuer that provides signed JSON Web Tokens (JWTs) to your workloads must be publicly accessible.
    • \n
\n

\"Project

\n

Ask AI

\n

reCAPTCHA

\n

Recaptcha requires verification.

\n

protected by reCAPTCHA

\n"}