From 15bad6c141f774bb3e8ef9d28f606349a9c4d426 Mon Sep 17 00:00:00 2001 From: Dominic R Date: Tue, 13 May 2025 11:01:32 -0400 Subject: [PATCH 01/14] init --- .../integrations/services/tailscale/index.md | 71 +++++++++++++++++++ website/sidebars/integrations.mjs | 1 + 2 files changed, 72 insertions(+) create mode 100644 website/integrations/services/tailscale/index.md diff --git a/website/integrations/services/tailscale/index.md b/website/integrations/services/tailscale/index.md new file mode 100644 index 000000000000..d419ad0d6732 --- /dev/null +++ b/website/integrations/services/tailscale/index.md @@ -0,0 +1,71 @@ +--- +title: Integrate with Tailscale +sidebar_label: Tailscale +support_level: community +--- + +## What is Tailscale + +> Tailscale is a mesh VPN service that creates secure, encrypted, peer-to-peer connections between devices across different networks using the WireGuard protocol. +> +> -- https://tailscale.com + +## Preparation + +The following placeholders are used in this guide: + +- `authentik.company` is the FQDN of the authentik installation. + +:::note +This documentation lists only the settings that you need to change from their default values. Be aware that any changes other than those explicitly mentioned in this guide could cause issues accessing your application. +::: + +## authentik configuration + +To support the integration of Tailscale with authentik, you need to create an application/provider pair in authentik. + +### Create an application and provider in authentik + +1. Log in to authentik as an admin, and open the authentik Admin interface. +2. Navigate to **Applications** > **Applications** and click **Create with Provider** to create an application and provider pair. (Alternatively you can first create a provider separately, then create the application and connect it with the provider.) + +- **Application**: provide a descriptive name, an optional group for the type of application, the policy engine mode, and optional UI settings. +- **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**,**Client Secret**, and **slug** values because they will be required later. + - Set a `Strict` redirect URI to `https://login.tailscale.com/a/oauth_response`. + - Select any available signing key. +- **Configure Bindings** _(optional)_: you can create a [binding](/docs/add-secure-apps/flows-stages/bindings/) (policy, group, or user) to manage the listing and access to applications on a user's **My applications** page. + +3. Click **Submit** to save the new application and provider. + +## Tailscale configuration + +:::warning WebFinger must be configured +Tailscale requires a WebFinger endpoint to be present at `.well-known/webfinger`. COnfiguration to do so depends on your web server or application hosted at root. You can use this example as the webfinger, replacing `your@email.com` with the admin email you'll use to create your Tailnet. +```json +{ + "links": [ + { + "href": "https://authentik.company", + "rel": "http://openid.net/specs/connect/1.0/issuer" + } + ], + "subject": "acct:your@email.com" +} +``` + +1. Visit the [Tailscale sign up page](https://login.tailscale.com/start) and click **Sign up with OIDC**. +2. Fill out the required information by setting the administrator email (must match the value set on the webfinger endpoint), then setting the identity provider type to `authentik`, and click **Get OIDC Issuer**. +3. Fill out the form: + - Under **Client ID**, set the Client ID which was copied from authentik. + - Under **Client secret**, set the Client secret which was copied from authentik. + - Leave the **Prompts** section to it's default value, `consent`. + +## Resources + +- [Tailscale SSO documentation](https://tailscale.com/kb/1240/sso-custom-oidc) + +## Configuration verification + +To confirm that authentik is properly configured with Tailscale, log out and attempt to log back in. Entering an email address under your SSO domain should redirect you to authentik. \ No newline at end of file diff --git a/website/sidebars/integrations.mjs b/website/sidebars/integrations.mjs index 39a16afe12fa..8db718f52431 100644 --- a/website/sidebars/integrations.mjs +++ b/website/sidebars/integrations.mjs @@ -122,6 +122,7 @@ const items = [ "services/netbird/index", "services/opnsense/index", "services/pfsense/index", + "services/tailscale/index", ], }, { From 8bc080596691e4f294d3fec8744572a9c053835d Mon Sep 17 00:00:00 2001 From: Dominic R Date: Tue, 13 May 2025 11:08:53 -0400 Subject: [PATCH 02/14] wording --- .../integrations/services/tailscale/index.md | 22 ++++++++++++------- 1 file changed, 14 insertions(+), 8 deletions(-) diff --git a/website/integrations/services/tailscale/index.md b/website/integrations/services/tailscale/index.md index d419ad0d6732..55fcefca273f 100644 --- a/website/integrations/services/tailscale/index.md +++ b/website/integrations/services/tailscale/index.md @@ -41,8 +41,10 @@ To support the integration of Tailscale with authentik, you need to create an ap ## Tailscale configuration -:::warning WebFinger must be configured -Tailscale requires a WebFinger endpoint to be present at `.well-known/webfinger`. COnfiguration to do so depends on your web server or application hosted at root. You can use this example as the webfinger, replacing `your@email.com` with the admin email you'll use to create your Tailnet. +:::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. + +Use this JSON template for your WebFinger response: ```json { "links": [ @@ -55,12 +57,16 @@ Tailscale requires a WebFinger endpoint to be present at `.well-known/webfinger` } ``` +**Important:** Replace `your@email.com` with the administrator email you'll use when creating your Tailnet. This email must match exactly in both the WebFinger configuration and during Tailscale setup. +::: + 1. Visit the [Tailscale sign up page](https://login.tailscale.com/start) and click **Sign up with OIDC**. -2. Fill out the required information by setting the administrator email (must match the value set on the webfinger endpoint), then setting the identity provider type to `authentik`, and click **Get OIDC Issuer**. -3. Fill out the form: - - Under **Client ID**, set the Client ID which was copied from authentik. - - Under **Client secret**, set the Client secret which was copied from authentik. - - Leave the **Prompts** section to it's default value, `consent`. +2. Enter the administrator email, select `authentik` as the identity provider type, and click **Get OIDC Issuer**. +3. Fill the form: + - Enter the Client ID copied from authentik in the **Client ID** field. + - Enter the Client secret copied from authentik in the **Client secret** field. + - Keep the default value `consent` in the **Prompts** section. +4. Click **Sign up with OIDC** and follow the prompts to complete the Tailscale-specific configuration. ## Resources @@ -68,4 +74,4 @@ Tailscale requires a WebFinger endpoint to be present at `.well-known/webfinger` ## Configuration verification -To confirm that authentik is properly configured with Tailscale, log out and attempt to log back in. Entering an email address under your SSO domain should redirect you to authentik. \ No newline at end of file +To verify the integration with Tailscale, log out and attempt to log back in. When you enter an email address from your configured SSO domain, you should be redirected to authentik. \ No newline at end of file From 0199af575fb6d078eba4629e649f8a0718818ec2 Mon Sep 17 00:00:00 2001 From: Dominic R Date: Tue, 13 May 2025 11:09:22 -0400 Subject: [PATCH 03/14] lint --- website/integrations/services/tailscale/index.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/website/integrations/services/tailscale/index.md b/website/integrations/services/tailscale/index.md index 55fcefca273f..551478e6f149 100644 --- a/website/integrations/services/tailscale/index.md +++ b/website/integrations/services/tailscale/index.md @@ -45,6 +45,7 @@ To support the integration of Tailscale with authentik, you need to create an ap 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. Use this JSON template for your WebFinger response: + ```json { "links": [ @@ -74,4 +75,4 @@ Use this JSON template for your WebFinger response: ## Configuration verification -To verify the integration with Tailscale, log out and attempt to log back in. When you enter an email address from your configured SSO domain, you should be redirected to authentik. \ No newline at end of file +To verify the integration with Tailscale, log out and attempt to log back in. When you enter an email address from your configured SSO domain, you should be redirected to authentik. From d011875e74eaf11fb3bbb978c4104ac0c81cdaff Mon Sep 17 00:00:00 2001 From: Dominic R Date: Tue, 13 May 2025 11:39:17 -0400 Subject: [PATCH 04/14] Update website/integrations/services/tailscale/index.md Signed-off-by: Dominic R --- website/integrations/services/tailscale/index.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/website/integrations/services/tailscale/index.md b/website/integrations/services/tailscale/index.md index 551478e6f149..7fad48451345 100644 --- a/website/integrations/services/tailscale/index.md +++ b/website/integrations/services/tailscale/index.md @@ -63,10 +63,10 @@ Use this JSON template for your WebFinger response: 1. Visit the [Tailscale 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**. -3. Fill the form: - - Enter the Client ID copied from authentik in the **Client ID** field. - - Enter the Client secret copied from authentik in the **Client secret** field. - - Keep the default value `consent` in the **Prompts** section. +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. ## Resources From d2fba5a7296a59ec7c5fe0ee496a69e4a9b1eda7 Mon Sep 17 00:00:00 2001 From: Dominic R Date: Tue, 13 May 2025 11:40:53 -0400 Subject: [PATCH 05/14] Dewi's suggestions --- .../integrations/services/tailscale/index.md | 40 +++++++++---------- 1 file changed, 20 insertions(+), 20 deletions(-) diff --git a/website/integrations/services/tailscale/index.md b/website/integrations/services/tailscale/index.md index 7fad48451345..f385d1b5f187 100644 --- a/website/integrations/services/tailscale/index.md +++ b/website/integrations/services/tailscale/index.md @@ -16,6 +16,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. + +Use this JSON template for your WebFinger response: + +```json +{ + "links": [ + { + "href": "https://authentik.company", + "rel": "http://openid.net/specs/connect/1.0/issuer" + } + ], + "subject": "acct:your@email.com" +} +``` + +**Important:** The domain in the email address must match both the domain where the WebFinger endpoint is served and the domain you will use for Tailscale. This email must match exactly in both the WebFinger configuration and during Tailscale setup. +::: + :::note This documentation lists only the settings that you need to change from their default values. Be aware that any changes other than those explicitly mentioned in this guide could cause issues accessing your application. ::: @@ -41,26 +61,6 @@ To support the integration of Tailscale with authentik, you need to create an ap ## Tailscale configuration -:::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. - -Use this JSON template for your WebFinger response: - -```json -{ - "links": [ - { - "href": "https://authentik.company", - "rel": "http://openid.net/specs/connect/1.0/issuer" - } - ], - "subject": "acct:your@email.com" -} -``` - -**Important:** Replace `your@email.com` with the administrator email you'll use when creating your Tailnet. This email must match exactly in both the WebFinger configuration and during Tailscale setup. -::: - 1. Visit the [Tailscale 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**. 3. Set the following configurations: From b75a7ca8bce7e8f3586d4950416778244b2934bb Mon Sep 17 00:00:00 2001 From: Dominic R Date: Tue, 13 May 2025 11:42:09 -0400 Subject: [PATCH 06/14] still mention that its a placeholder --- website/integrations/services/tailscale/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/integrations/services/tailscale/index.md b/website/integrations/services/tailscale/index.md index f385d1b5f187..2c9c1a230a29 100644 --- a/website/integrations/services/tailscale/index.md +++ b/website/integrations/services/tailscale/index.md @@ -33,7 +33,7 @@ Use this JSON template for your WebFinger response: } ``` -**Important:** The domain in the email address must match both the domain where the WebFinger endpoint is served and the domain you will use for Tailscale. This email must match exactly in both the WebFinger configuration and during Tailscale setup. +**Important:** Replace `your@email.com` with the administrator email you'll use when creating your Tailnet. The domain in the email address must match both the domain where the WebFinger endpoint is served and the domain you will use for Tailscale. This email must match exactly in both the WebFinger configuration and during Tailscale setup. ::: :::note From 22fe03be1df9cabe410796f6b7155c0399b2195b Mon Sep 17 00:00:00 2001 From: Dominic R Date: Wed, 28 May 2025 19:00:34 -0400 Subject: [PATCH 07/14] fix Signed-off-by: Dominic R --- website/integrations/services/tailscale/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/integrations/services/tailscale/index.md b/website/integrations/services/tailscale/index.md index 2c9c1a230a29..1eda9e5ab986 100644 --- a/website/integrations/services/tailscale/index.md +++ b/website/integrations/services/tailscale/index.md @@ -46,7 +46,7 @@ To support the integration of Tailscale with authentik, you need to create an ap ### Create an application and provider in authentik -1. Log in to authentik as an admin, and open the authentik Admin interface. +1. Log in to authentik as an administrator and open the authentik Admin interface. 2. Navigate to **Applications** > **Applications** and click **Create with Provider** to create an application and provider pair. (Alternatively you can first create a provider separately, then create the application and connect it with the provider.) - **Application**: provide a descriptive name, an optional group for the type of application, the policy engine mode, and optional UI settings. From 7d769a17a0e1f988316fb43b938cbd67937ee971 Mon Sep 17 00:00:00 2001 From: Dominic R Date: Thu, 29 May 2025 08:29:04 -0400 Subject: [PATCH 08/14] Update website/integrations/services/tailscale/index.md Co-authored-by: Dewi Roberts Signed-off-by: Dominic R --- website/integrations/services/tailscale/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/integrations/services/tailscale/index.md b/website/integrations/services/tailscale/index.md index 1eda9e5ab986..a576a38b9ac9 100644 --- a/website/integrations/services/tailscale/index.md +++ b/website/integrations/services/tailscale/index.md @@ -75,4 +75,4 @@ To support the integration of Tailscale with authentik, you need to create an ap ## Configuration verification -To verify the integration with Tailscale, log out and attempt to log back in. When you enter an email address from your configured SSO domain, you should be redirected to authentik. +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. From ed0f8c4fc83e4bee8b88b34846ea57d85c59320b Mon Sep 17 00:00:00 2001 From: Dominic R Date: Thu, 29 May 2025 08:30:37 -0400 Subject: [PATCH 09/14] mv to end Signed-off-by: Dominic R --- website/integrations/services/tailscale/index.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/website/integrations/services/tailscale/index.md b/website/integrations/services/tailscale/index.md index a576a38b9ac9..de45aa4f2a6d 100644 --- a/website/integrations/services/tailscale/index.md +++ b/website/integrations/services/tailscale/index.md @@ -69,10 +69,10 @@ To support the integration of Tailscale with authentik, you need to create an ap - **Prompts**: keep the default value `consent`. 4. Click **Sign up with OIDC** and follow the prompts to complete the Tailscale-specific configuration. -## Resources - -- [Tailscale SSO documentation](https://tailscale.com/kb/1240/sso-custom-oidc) - ## 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. + +## Resources + +- [Tailscale SSO documentation](https://tailscale.com/kb/1240/sso-custom-oidc) From e4770129ba3c4bcf1b3384699dfba157ff6899bb Mon Sep 17 00:00:00 2001 From: Dominic R Date: Thu, 29 May 2025 19:22:55 -0400 Subject: [PATCH 10/14] indent --- website/integrations/services/tailscale/index.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/website/integrations/services/tailscale/index.md b/website/integrations/services/tailscale/index.md index de45aa4f2a6d..049ee5fd75a6 100644 --- a/website/integrations/services/tailscale/index.md +++ b/website/integrations/services/tailscale/index.md @@ -49,13 +49,13 @@ 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 **Create with Provider** to create an application and provider pair. (Alternatively you can first create a provider separately, then create the application and connect it with the provider.) -- **Application**: provide a descriptive name, an optional group for the type of application, the policy engine mode, and optional UI settings. -- **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**,**Client Secret**, and **slug** values because they will be required later. - - Set a `Strict` redirect URI to `https://login.tailscale.com/a/oauth_response`. - - Select any available signing key. -- **Configure Bindings** _(optional)_: you can create a [binding](/docs/add-secure-apps/flows-stages/bindings/) (policy, group, or user) to manage the listing and access to applications on a user's **My applications** page. + - **Application**: provide a descriptive name, an optional group for the type of application, the policy engine mode, and optional UI settings. + - **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**,**Client Secret**, and **slug** values because they will be required later. + - Set a `Strict` redirect URI to `https://login.tailscale.com/a/oauth_response`. + - Select any available signing key. + - **Configure Bindings** _(optional)_: you can create a [binding](/docs/add-secure-apps/flows-stages/bindings/) (policy, group, or user) to manage the listing and access to applications on a user's **My applications** page. 3. Click **Submit** to save the new application and provider. From 898dfca3cfdbea3dd62854c1bd6f56792840f16a Mon Sep 17 00:00:00 2001 From: Dominic R Date: Fri, 30 May 2025 08:27:42 -0400 Subject: [PATCH 11/14] Update website/integrations/services/tailscale/index.md Co-authored-by: Dewi Roberts Signed-off-by: Dominic R --- website/integrations/services/tailscale/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/integrations/services/tailscale/index.md b/website/integrations/services/tailscale/index.md index 049ee5fd75a6..d08c95c3cc79 100644 --- a/website/integrations/services/tailscale/index.md +++ b/website/integrations/services/tailscale/index.md @@ -33,7 +33,7 @@ Use this JSON template for your WebFinger response: } ``` -**Important:** Replace `your@email.com` with the administrator email you'll use when creating your Tailnet. The domain in the email address must match both the domain where the WebFinger endpoint is served and the domain you will use for Tailscale. This email must match exactly in both the WebFinger configuration and during Tailscale setup. +**Important:** Replace `your@email.com` with the administrator email you'll 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. ::: :::note From f5eb5c0073d415844e779b7955b073f476a1b835 Mon Sep 17 00:00:00 2001 From: Dominic R Date: Fri, 30 May 2025 08:29:42 -0400 Subject: [PATCH 12/14] Update website/integrations/services/tailscale/index.md Signed-off-by: Dominic R --- website/integrations/services/tailscale/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/integrations/services/tailscale/index.md b/website/integrations/services/tailscale/index.md index d08c95c3cc79..c3ab1805b473 100644 --- a/website/integrations/services/tailscale/index.md +++ b/website/integrations/services/tailscale/index.md @@ -52,7 +52,7 @@ To support the integration of Tailscale with authentik, you need to create an ap - **Application**: provide a descriptive name, an optional group for the type of application, the policy engine mode, and optional UI settings. - **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**,**Client Secret**, and **slug** values because they will be required later. + - Note the **Client ID** and **Client Secret** values because they will be required later. - Set a `Strict` redirect URI to `https://login.tailscale.com/a/oauth_response`. - Select any available signing key. - **Configure Bindings** _(optional)_: you can create a [binding](/docs/add-secure-apps/flows-stages/bindings/) (policy, group, or user) to manage the listing and access to applications on a user's **My applications** page. From e2b84c4610c92187c8972e8b7bdbc38df93de2b4 Mon Sep 17 00:00:00 2001 From: Tana M Berry Date: Tue, 3 Jun 2025 18:07:19 -0500 Subject: [PATCH 13/14] tweak to bump build --- website/integrations/services/tailscale/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/integrations/services/tailscale/index.md b/website/integrations/services/tailscale/index.md index c3ab1805b473..5092296125de 100644 --- a/website/integrations/services/tailscale/index.md +++ b/website/integrations/services/tailscale/index.md @@ -33,7 +33,7 @@ Use this JSON template for your WebFinger response: } ``` -**Important:** Replace `your@email.com` with the administrator email you'll 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. +**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. ::: :::note From e0ecf4aed3d2b21ad835715c335bbbaff9c3e43d Mon Sep 17 00:00:00 2001 From: Tana M Berry Date: Tue, 3 Jun 2025 19:43:43 -0500 Subject: [PATCH 14/14] another tweak to bump build --- website/integrations/services/tailscale/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/integrations/services/tailscale/index.md b/website/integrations/services/tailscale/index.md index 5092296125de..7c19f4e19b4c 100644 --- a/website/integrations/services/tailscale/index.md +++ b/website/integrations/services/tailscale/index.md @@ -61,7 +61,7 @@ To support the integration of Tailscale with authentik, you need to create an ap ## Tailscale configuration -1. Visit the [Tailscale sign up page](https://login.tailscale.com/start) and click **Sign up with OIDC**. +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**. 3. Set the following configurations: - **Client ID**: enter the Client ID copied from authentik.