Tailscale

Namespace relies on workload identity federation to connect your workloads to your Tailscale tailnet. To get started, you need a Tailscale OIDC client ID and the set of tags that Namespace workloads should advertise when they register.

At runtime, Namespace issues a short-lived OpenID Connect ID token and uses it to register the workload with your tailnet. No long-lived Tailscale auth key or client secret needs to be stored in Namespace.

Configure Tailscale

Use the Tailscale admin console to create the client ID that Namespace will store.

Create an OpenID Connect trust credential

Open Tailscale's Trust credentials page, select Credential, then choose OpenID Connect.

Configure Namespace as the issuer

Configure the credential to trust Namespace's OIDC issuer:

• Issuer: Custom issuer
• Issuer URL: https://federation.namespaceapis.com
• Subject: <workspace-id>/*

The subject pattern above allows workloads from one Namespace workspace to join your tailnet. Namespace issues ID tokens with subjects in the form <workspace-id>/<instance-id> for workloads.

You can find your workspace ID in Workspace settings.

Grant node-registration access and tags

Grant the credential the ability to register nodes and select the tags that Namespace workloads are allowed to advertise. The tags you save in Namespace must be a subset of the tags allowed here.

For Namespace-managed node registration, enable the scope that allows auth key generation for node joins:

• Scope: auth_keys
• Tags: every tag you plan to pass through nsc integrations tailscale set --tag ...

After you generate the credential, Tailscale shows both a Client ID and an Audience. Namespace only needs the Client ID. It automatically requests an ID token with audience api.tailscale.com/<client-id>.

Configure the integration in Namespace

Once you have the Tailscale client ID, store it in your Namespace workspace with a friendly name:

$
nsc integrations tailscale set corp --oauth-client-id <tailscale-client-id> --tag tag:namespace --tag tag:ci

This command creates or replaces the named spec corp. The stored tags are the tags Namespace passes to tailscale up --advertise-tags=... when the workload joins your tailnet.

You can pass tags either multiple times or as a comma-separated list:

nsc integrations tailscale set corp \
  --oauth-client-id <tailscale-client-id> \
  --tag tag:namespace,tag:ci

Inspect And Remove Specs

List the currently configured Tailscale specs in your workspace:

$
nsc integrations tailscale list

To inspect the full machine-readable response instead, use JSON output:

$
nsc integrations tailscale list --output json

Remove a named spec when you no longer need it:

$
nsc integrations tailscale remove corp

How Namespace Uses The Spec

When a Namespace workload uses one of these named specs, Namespace resolves the saved client ID and tags, issues a short-lived ID token from https://federation.namespaceapis.com, and joins Tailscale with:

tailscale up \
  --client-id="<tailscale-client-id>?preauthorized=true" \
  --id-token="$ID_TOKEN" \
  --advertise-tags=tag:namespace,tag:ci

This means:

• You keep long-lived Tailscale secrets out of Namespace
• Each workload authenticates with a short-lived Namespace-issued OIDC token
• Tailscale authorization stays scoped to the workspace and tags you configured above

Notes

• Tailscale integration is currently supported for Linux workloads.
• The named integration only stores the client ID and tags; it does not store a Tailscale client secret.
• If Tailscale rejects the advertised tags, check that the same tags are allowed on the Tailscale trust credential.
• For more background on Namespace-issued OIDC tokens, see Workload Federation with OpenID Connect.