From 6b04fe2652d1f7a3b42fcb4907319ea99d8139d4 Mon Sep 17 00:00:00 2001 From: Amir Zarrinkafsh Date: Wed, 3 May 2023 11:29:55 +1000 Subject: [PATCH] docs: fix tailscale oidc typos and inaccuracies (#5367) Adjusts some inaccuracies and inconsistencies. Fixes #5359 Signed-off-by: Amir Zarrinkafsh --- .../openid-connect/tailscale/index.md | 48 +++++++++++-------- 1 file changed, 27 insertions(+), 21 deletions(-) diff --git a/docs/content/en/integration/openid-connect/tailscale/index.md b/docs/content/en/integration/openid-connect/tailscale/index.md index e8c35d1a6..2129f4155 100644 --- a/docs/content/en/integration/openid-connect/tailscale/index.md +++ b/docs/content/en/integration/openid-connect/tailscale/index.md @@ -17,7 +17,7 @@ community: true * [Authelia] * [v4.37.5](https://github.com/authelia/authelia/releases/tag/v4.37.5) -* [Tailscale] - Note: Version not important, since configuration is via the web UI +* [Tailscale] - **Note:** Version not important, since configuration is via the WebUI * [1.38.4](https://github.com/tailscale/tailscale/releases/tag/v1.38.4) ## Before You Begin @@ -36,35 +36,39 @@ This example makes the following assumptions: ## Configuration -The configuration in Authelia is straightforwarded: Tailscale is just another `identity_provider/oidc` entry. Complicating things is the necessary WebFinger reply for your domain - see the following [Application](#application) section. +The configuration in Authelia is straight forward, Tailscale is just another `identity_provider/oidc` entry. +Tailscale also requires a WebFinger reply for your domain - see the following [Application](#application) +section. ### Application -To configure [Tailscale] to utilize Authelia as an [OpenID Connect 1.0] Provider, you will need a public WebFinger reply for your domain (see [RFC 7033](https://www.rfc-editor.org/rfc/rfc7033#section-3.1)) and point it to Authelia. The steps necessary are outlined in the Tailscale documentation on [Custom OIDC providers](https://tailscale.com/kb/1240/sso-custom-oidc/). This WebFinger reply is not generated by Authelia, so your external webserver hosted at the root of your domain will need to generate the reponse (Check [See also](#see-also) for example implementations). The following steps are necessary to get Tailscale working with Authelia: +To configure [Tailscale] to utilize Authelia as a [OpenID Connect 1.0] Provider, you will need a public WebFinger reply +for your domain (see [RFC7033 Section 3.1]) and point it to Authelia. The steps necessary are outlined in the Tailscale +documentation on [Custom OIDC providers KB article]. This WebFinger reply is not generated by Authelia, so your external +webserver hosted at the root of your domain will need to generate the response (Check [See also](#see-also) for example +implementations). The following steps are necessary to get Tailscale working with Authelia: 1. Your domain will need to reply to a WebFinger request for your Authelia account -2. Your domain root is `example.com` and the Authelia account in question is `user@example.com`, the WebFinger request will be: `https://example.com/.well-known/webfinger/?resource=acct:user@example.com` (the complete request is `https://example.com/.well-known/webfinger?rel=http%3A%2F%2Fopenid.net%2Fspecs%2Fconnect%2F1.0%2Fissuer&resource=acct%3Auser%40example.com`) +2. Your domain root is `example.com` and the Authelia account in question is `user@example.com` the WebFinger request +will be: `https://example.com/.well-known/webfinger/?resource=acct:user@example.com the complete request is `https://example.com/.well-known/webfinger?rel=http%3A%2F%2Fopenid.net%2Fspecs%2Fconnect%2F1.0%2Fissuer&resource=acct%3Auser%40example.com` 3. The WebFinger request needs to be answered with the following example reply: -``` +```json { - "subject" : "acct:user@example.com", - "links" : - [ - { - "rel" : "http://openid.net/specs/connect/1.0/issuer", - "href" : "https://auth.example.com" - } - ] + "subject": "acct:user@example.com", + "links": [{ + "rel": "http://openid.net/specs/connect/1.0/issuer", + "href": "https://auth.example.com" + }] } ``` -4. For any other users that you want to add to Tailscale, you will need to to provide similar WebFinger replies (e.g. for `user2@example.com` or `user3@example.com`) -5. Once you have the WebFinger reply set up and your [Authelia OpenID Connect Discovery endpoint](https://www.authelia.com/integration/openid-connect/introduction/#well-known-discovery-endpoints) is working (e.g. `https://auth.example.com/.well-known/openid-configuration`), you can sign up for a **new Tailnet** (currently migration isn't supported) via the link: [Sign up with OIDC](https://login.tailscale.com/start/oidc) where you will see the following screen: -{{< figure src="tailscale_signup_1.png" alt="Tailscale Signup Screen 1" width="300" >}} +4. For any other users that you want to add to Tailscale, you will need to provide similar WebFinger replies (e.g. for `user2@example.com` or `user3@example.com`) +5. Once you have the WebFinger reply set up and your [Authelia OpenID Connect Discovery endpoint](https://www.authelia.com/integration/openid-connect/introduction/#well-known-discovery-endpoints) is working (e.g. `https://auth.example.com/.well-known/openid-configuration`), you can sign up for a **new Tailnet** (migration can only be done if the Tailnet is associated with a custom domain) via the link: [Sign up with OIDC](https://login.tailscale.com/start/oidc) where you will see the following screen: \ +{{< figure src="tailscale_signup_1.png" alt="Tailscale Signup Screen 1" width="300" >}} \ **Note:** Even though the WebFinger URL displayed is `https://example.com/.well-known/webfinger`, the actual GET request will be including request parameters, most importantly `resource`. -6. After clicking on **Get OIDC Issuer**, Tailscale will fetch the WebFinger reply via `https://example.com/.well-known/webfinger/?resource=acct:user@example.com` and follow the set `href` to `https://auth.example.com/.well-known/openid-configuration`. -**Note:** make sure that the `href` URL matches the `issuer` URL returned from the Authelia OIDC dicsovery endpoint -7. On the next screen you will need to add your client ID & secret configured in Authelia to finish the OIDC provider registration in [Tailscale]. See the following example screenshot: +6. After clicking on **Get OIDC Issuer**, Tailscale will fetch the WebFinger reply via `https://example.com/.well-known/webfinger/?resource=acct:user@example.com` and follow the set `href` to `https://auth.example.com/.well-known/openid-configuration`. \ +**Note:** Make sure that the `href` URL matches the `issuer` URL returned from the Authelia OIDC discovery endpoint +7. On the next screen you will need to add your client ID & secret configured in Authelia to finish the OIDC provider registration in [Tailscale]. See the following example screenshot: \ {{< figure src="tailscale_signup_2.png" alt="Tailscale Signup Screen 2" width="300" >}} @@ -93,10 +97,12 @@ identity_providers: ## See Also -- [Tailscale] [Custom OIDC Provider Knowledge Base entry](https://tailscale.com/kb/1240/sso-custom-oidc/): -- [RFC 7033, Identity Provider Discovery for OpenID Connect](https://www.rfc-editor.org/rfc/rfc7033#section-3.1) +- [Tailscale] [Custom OIDC providers KB article] +- [RFC7033 Section 3.1] _WebFinger: Identity Provider Discovery for OpenID Connect_ - [WebFinger example implementations](https://webfinger.net/code/) [Authelia]: https://www.authelia.com [Tailscale]: https://tailscale.com +[Custom OIDC providers KB article]: https://tailscale.com/kb/1240/sso-custom-oidc/ +[RFC7033 Section 3.1]: https://datatracker.ietf.org/doc/html/rfc7033#section-3.1 [OpenID Connect 1.0]: ../../openid-connect/introduction.md