action.yml,src: add support for workload identity federation

Add support for workload identity federation based authentication.

Updates tailscale/corp#31264

Signed-off-by: Mario Minardi <[email protected]>

Author: mpminardi

README.md

@@ -14,29 +14,58 @@ by adding a step to your workflow.
 
 Subsequent steps in the Action can then access nodes in your Tailnet.
 
-oauth-client-id and oauth-secret are an [OAuth client](https://tailscale.com/s/oauth-clients/)
+oauth-client-id and oauth-secret are an [OAuth client][kb-oauth-clients]
 for the tailnet to be accessed. We recommend storing these as
 [GitHub Encrypted Secrets.](https://docs.github.com/en/actions/security-guides/encrypted-secrets)
 OAuth clients used for this purpose must have the
-[`auth_keys` scope.](https://tailscale.com/kb/1215/oauth-clients#scopes)
+[`auth_keys` scope.][kb-trust-credentials-scopes]
 
-tags is a comma-separated list of one or more [ACL Tags](https://tailscale.com/kb/1068/acl-tags/)
+tags is a comma-separated list of one or more [Tags][kb-tags]
 for the node. At least one tag is required: an OAuth client is not associated
 with any of the Users on the tailnet, it has to Tag its nodes.
 
-Nodes created by this Action are [marked as Ephemeral](https://tailscale.com/s/ephemeral-nodes) to
+Nodes created by this Action are [marked as Ephemeral][kb-ephemeral-nodes] to
 and log out immediately after finishing their CI run, at which point they are automatically removed
-by the coordination server. The nodes are also [marked Preapproved](https://tailscale.com/kb/1085/auth-keys/)
-on tailnets which use [Device Approval](https://tailscale.com/kb/1099/device-approval/)
+by the coordination server. The nodes are also [marked Preapproved][kb-auth-keys]
+on tailnets which use [Device Approval][kb-device-approval]
+
+
+### Workload identity federation
+[Workload identity federation][kb-workload-identity-federation] can also be used for authenticating nodes with your tailnet:
+
+```yaml
+- name: Tailscale
+  uses: tailscale/github-action@v4
+  with:
+    oauth-client-id: ${{ secrets.TS_OAUTH_CLIENT_ID }}
+    audience: ${{ secrets.TS_AUDIENCE }}
+    tags: tag:ci
+```
+
+Workload 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:
+
+```yaml
+permissions:
+  id-token: write # This is required for the tailscale action to request a JWT from GitHub
+```
+
+Federated identity credentials used for this purpose must have the [`auth_keys` scope.][kb-trust-credentials-scopes]
+
+tags is a comma-separated list of one or more [Tags][kb-tags]
+for the node. At least one tag is required: a federated identity is not associated
+with any of the Users on the tailnet, it has to Tag its nodes.
+
+> [!IMPORTANT]
+> Tailscale version `1.90.1` or later is required for workload identity federation.
 
 ## Prerequisites
 
 Before using the Tailscale GitHub Action, ensure you have the following:
 
-1. A Tailscale account with <Role>Owner, Admin, or Network admin</Role> permissions.
+1. A Tailscale account with Owner, Admin, or Network admin permissions.
 1. A GitHub repository that you have admin access to (required to set up the GitHub Action).
-1. At least one configured [tag][kb-tags].
-1. An [OAuth client][kb-oauth-clients] ID and secret OR an [auth key][kb-auth-keys].
+1. At least one configured [tag][kb-tags] if using OAuth or workload identity federation.
+1. An [OAuth client][kb-oauth-clients] ID and secret, [federated identity][kb-workload-identity-federation] client ID and audience, OR an [auth key][kb-auth-keys].
 1. A runner image version >= 2.237.1 (required to support running Node.js 24).
 
 ## Eventual consistency
@@ -55,22 +84,21 @@ You can do this by adding a list of hosts to ping to the action configuration:
     ping: 100.x.y.z,my-machine.my-tailnet.ts.net
 ```
 
-or with the [tailscale ping](https://tailscale.com/kb/1080/cli#ping) command if you do not know the peers at the time of installing Tailscale in the workflow:
+or with the [tailscale ping][kb-cli-ping] command if you do not know the peers at the time of installing Tailscale in the workflow:
 
 ```bash
 tailscale ping my-target.my-tailnet.ts.net
 ```
 
-The `ping` option will wait up to to 3 minutes for a connection (direct or relayed).
+The `ping` option will wait up to 3 minutes for a connection (direct or relayed).
 
 ## Tailnet Lock
 
-If you are using this Action in a [Tailnet
-Lock](https://tailscale.com/kb/1226/tailnet-lock) enabled network, you need to:
+If you are using this Action in a [Tailnet Lock][kb-tailnet-lock] enabled network, you need to:
 
-- Authenticate using an ephemeral reusable [pre-signed auth key](https://tailscale.com/kb/1226/tailnet-lock#add-a-node-using-a-pre-signed-auth-key)
+- Authenticate using an ephemeral reusable [pre-signed auth key][kb-tailnet-lock-pre-signed]
   rather than an OAuth client.
-- Specify a [state directory](https://tailscale.com/kb/1278/tailscaled#flags-to-tailscaled) for the
+- Specify a [state directory][kb-tailscaled-flags] for the
   client to store the Tailnet Key Authority data in.
 
 ```yaml
@@ -139,4 +167,16 @@ the GitHub Action leaves tailscale binaries installed but stops the tailscale ba
 
 ### requested tags [tag:mytag] are invalid or not permitted
 
-You may encounter this error when using an OAuth client. OAuth clients must have the [`auth_keys` scope](https://tailscale.com/kb/1215/oauth-clients#scopes) with one or more [tags](https://tailscale.com/kb/1068/acl-tags/), and the tags specified with `tags` must match all tags on the OAuth client.
+You may encounter this error when using an OAuth client. OAuth clients must have the [`auth_keys` scope][kb-trust-credentials-scopes] with one or more [tags][kb-tags], and the tags specified with `tags` must match all tags on the OAuth client.
+
+[kb-auth-keys]: https://tailscale.com/kb/1085/auth-keys
+[kb-cli-ping]: https://tailscale.com/kb/1080/cli#ping
+[kb-device-approval]: https://tailscale.com/kb/1099/device-approval
+[kb-ephemeral-nodes]: https://tailscale.com/kb/1111/ephemeral-nodes
+[kb-oauth-clients]: https://tailscale.com/kb/1215/oauth-clients
+[kb-tags]: https://tailscale.com/kb/1068/tags
+[kb-tailnet-lock]: https://tailscale.com/kb/1226/tailnet-lock
+[kb-tailnet-lock-pre-signed]: https://tailscale.com/kb/1226/tailnet-lock#add-a-node-using-a-pre-signed-auth-key
+[kb-tailscaled-flags]: https://tailscale.com/kb/1278/tailscaled#flags-to-tailscaled
+[kb-trust-credentials-scopes]: https://tailscale.com/kb/1623/trust-credentials#scopes
+[kb-workload-identity-federation]: https://tailscale.com/kb/1581/workload-identity-federation

action.yml

@@ -13,7 +13,10 @@ inputs:
     required: false
     deprecationMessage: 'An OAuth API client https://tailscale.com/s/oauth-clients is recommended instead of an authkey'
   oauth-client-id:
-    description: 'Your Tailscale OAuth Client ID.'
+    description: 'Your Tailscale OAuth or Workload Identity Federation Client ID.'
+    required: false
+  audience:
+    description: 'Your Tailscale Workload Identity Federation Audience'
     required: false
   oauth-secret:
     description: 'Your Tailscale OAuth Client Secret.'

dist/index.js

@@ -30,6 +30,7 @@ interface TailscaleConfig {
   arch: string;
   authKey: string;
   oauthClientId: string;
+  audience: string;
   oauthSecret: string;
   tags: string;
   hostname: string;
@@ -214,6 +215,7 @@ async function getInputs(): Promise<TailscaleConfig> {
     arch: "",
     authKey: authKey,
     oauthClientId: core.getInput("oauth-client-id") || "",
+    audience: core.getInput("audience") || "",
     oauthSecret: oauthSecret,
     tags: core.getInput("tags") || "",
     hostname: core.getInput("hostname") || "",
@@ -237,9 +239,13 @@ async function getInputs(): Promise<TailscaleConfig> {
 }
 
 function validateAuth(config: TailscaleConfig): void {
-  if (!config.authKey && (!config.oauthSecret || !config.tags)) {
+  if (
+    !config.authKey &&
+    (!config.oauthSecret || !config.tags) &&
+    (!config.audience || !config.oauthClientId || !config.tags)
+  ) {
     throw new Error(
-      "OAuth identity empty, please provide either an auth key or OAuth secret and tags."
+      "Please provide either an auth key, OAuth secret and tags, or federated identity client ID and audience with tags."
     );
   }
 }
@@ -678,14 +684,24 @@ async function connectToTailscale(
   hostname = hostname.substring(0, 63);
 
   // Prepare auth and tags
-  let finalAuthKey = config.authKey;
+  const authArgs: string[] = [];
   const tagsArg: string[] = [];
 
-  if (config.oauthSecret) {
-    finalAuthKey = `${config.oauthSecret}?preauthorized=true&ephemeral=true`;
+  if (config.authKey) {
+    authArgs.push(`--authkey=${config.authKey}`);
+  } else {
     tagsArg.push(`--advertise-tags=${config.tags}`);
-  }
 
+    if (config.oauthSecret) {
+      authArgs.push(
+        `--authkey=${config.oauthSecret}?preauthorized=true&ephemeral=true`
+      );
+    } else if (config.audience) {
+      const token = await core.getIDToken(config.audience);
+      authArgs.push(`--client-id=${config.oauthClientId}`);
+      authArgs.push(`--id-token=${token}`);
+    }
+  }
   // Platform-specific args
   const platformArgs: string[] = [];
   if (runnerOS === runnerWindows) {
@@ -696,11 +712,11 @@ async function connectToTailscale(
   const upArgs = [
     "up",
     ...tagsArg,
-    `--authkey=${finalAuthKey}`,
     `--hostname=${hostname}`,
     "--accept-routes",
     ...platformArgs,
     ...config.args.split(" ").filter(Boolean),
+    ...authArgs,
   ];
 
   // Retry logic