diff --git a/website/integrations/networking/tailscale/index.md b/website/integrations/networking/tailscale/index.md index 859640e4a6..945a27f1bd 100644 --- a/website/integrations/networking/tailscale/index.md +++ b/website/integrations/networking/tailscale/index.md @@ -18,24 +18,26 @@ The following placeholders are used in this guide: - `authentik.company` is the FQDN of the authentik installation. -:::info -Tailscale requires a properly configured WebFinger endpoint at `.well-known/webfinger` on the domain used for your email. Set this up according to your web server or application specifications. +This guide covers creating a new tailnet with custom OIDC. To migrate an existing tailnet to custom OIDC, contact Tailscale support after configuring WebFinger. + +:::info WebFinger endpoint required +Tailscale requires a WebFinger endpoint at `https://example.com/.well-known/webfinger` on the domain used for your administrator email address. Set this up according to your web server or application specifications. Use this JSON template for your WebFinger response: ```json { + "subject": "acct:admin@example.com", "links": [ { "href": "https://authentik.company/application/o//", "rel": "http://openid.net/specs/connect/1.0/issuer" } - ], - "subject": "acct:your@email.com" + ] } ``` -**Important:** Replace `your@email.com` with the administrator email that you will use when creating your Tailnet. The domain in the email address must match the domain where the WebFinger endpoint is served and the domain you will use for Tailscale. +Replace `admin@example.com` with the administrator email address that you will use when creating your tailnet. The domain in the email address must match the domain where the WebFinger endpoint is served and the domain you will use for Tailscale. The issuer URL must exactly match the issuer in authentik's OpenID configuration, and both the WebFinger endpoint and authentik issuer must be reachable by Tailscale. ::: :::info @@ -52,7 +54,7 @@ To support the integration of Tailscale with authentik, you need to create an ap 1. Log in to authentik as an administrator and open the authentik Admin interface. 2. Navigate to **Applications** > **Applications** and click **New Application** to open the application wizard. - - **Application**: provide a descriptive name, an optional group for the type of application, the policy engine mode, and optional UI settings. + - **Application**: provide a descriptive name, an optional group for the type of application, the policy engine mode, and optional UI settings. Note the **Slug** value because it will be required for the WebFinger response. - **Choose a Provider type**: select **OAuth2/OpenID Connect** as the provider type. - **Configure the Provider**: provide a name (or accept the auto-provided name), the authorization flow to use for this provider, and the following required configurations. - Note the **Client ID** and **Client Secret** values because they will be required later. @@ -64,18 +66,17 @@ To support the integration of Tailscale with authentik, you need to create an ap ## Tailscale configuration -1. Visit [Tailscale's sign up page](https://login.tailscale.com/start) and click **Sign up with OIDC**. -2. Enter the administrator email, select `authentik` as the identity provider type, and click **Get OIDC Issuer**. +1. Open Tailscale's [Sign up with OIDC](https://login.tailscale.com/start/oidc) page. +2. Enter the administrator email address that matches your WebFinger endpoint and click **Get OIDC Issuer**. If prompted for an identity provider type, select **authentik**. 3. Set the following configurations: - - **Client ID**: enter the Client ID copied from authentik. - - **Client secret**: enter the Client secret copied from authentik. - - **Prompts**: keep the default value `consent`. -4. Click **Sign up with OIDC** and follow the prompts to complete the Tailscale-specific configuration. + - **Client ID**: enter the client ID from authentik. + - **Client secret**: enter the client secret from authentik. +4. Click **Sign up with OIDC** and authenticate with authentik using the administrator email address from the previous step. ## Configuration verification -To verify the integration with Tailscale, log out and attempt to log back in using an email address from your configured SSO domain. You should be redirected to your authentik instance and after successfully logging in, you should be redirected to the Tailscale dashboard. +To verify the integration with Tailscale, open Tailscale and log in using an email address from your configured SSO domain. You should be redirected to authentik and then back to the Tailscale admin console. ## Resources -- [Tailscale SSO documentation](https://tailscale.com/kb/1240/sso-custom-oidc) +- [Tailscale custom OIDC providers documentation](https://tailscale.com/docs/integrations/identity/custom-oidc)