Custom OIDC providers

Tailscale can integrate with identity providers that support OpenID Connect (OIDC). The steps provided in this topic are required only for initial creation of a tailnet. After the signup process is completed, Tailscale will work like any other supported identity provider. For more information about OIDC, refer to Welcome to OpenID Connect.

Requirements

• Proof of domain ownership and OIDC discovery using WebFinger.
• An identity provider with SSO based on OIDC, that uses openid, profile, and email scopes, and provides for a callback URL.
• The OIDC provider must use either ES256 or RSA signatures; the minimum RSA key size is 2048 bits.

WebFinger setup

To use a custom OIDC provider with Tailscale, you must set up a WebFinger endpoint on your domain. WebFinger verifies that you have administrative control over a domain and issuer URL discovery. For more detailed information about using WebFinger with OIDC issuer discovery, refer to RFC 7033.

The WebFinger endpoint must be served at https://${domain}/.well-known/webfinger and must include the issuer URL within the JRD in the response. For example:

{
  "subject": "acct:${email}",
  "links": [
    {
      "rel": "http://openid.net/specs/connect/1.0/issuer",
      "href": "${issuer URL}"
    }
  ]
}

The WebFinger endpoint must be hosted at the domain of the email address provided during setup. The issuer URL specified in your JRD must exactly match the issuer URL in your /.well-known/openid-configuration. For more information, refer to the Identity Provider Discovery for OpenID Connect section in the RFC 7033: WebFinger specification.

To verify your WebFinger endpoint:

1. In your browser, open the WebFinger Lookup tool.
2. In the Lookup WebFinger search box, enter the user's email address.
3. Select the search icon.
4. Examine the results to determine if your endpoint is valid.

Identity provider setup

The identity provider used for your custom OIDC setup must comply with the OIDC specification and the Tailscale requirements.

Tailscale requires you to provide the following:

• Issuer URL retrieved from the WebFinger endpoint, described in the previous section.
• Client ID.
• Client secret from your identity provider.

Scopes specify the required information to include in the authentication request. The required scopes are openid, profile, and email. Tailscale requests the minimum number scopes required to operate, and the information on how we use your data can be found in our privacy policy.

Prompts specify the requirements and behavior on the authentication page for the user. Prompts are optional, and the supported values within the Tailscale setup UI are none, consent (the default), login, and select_account. Note that individual identity providers or identity provider configuration may not support any or all of these values. For more information, refer to the OIDC Authentication Request specification.

Callback URL must be configured in your identity provider settings, with the following URL:

https://login.tailscale.com/a/oauth_response

Additional provider configurations

Specific identity providers may require additional configurations:

Tailscale setup

1. Go to the Sign up with OIDC page of the admin console.

   Or, when signing up for your Tailscale account, select Sign up with OIDC.

   

2. In the Email address field, enter the administrator's full email address. The domain in the email address must match the domain where the WebFinger endpoint is served, and the domain you will use for Tailscale.

3. Select Get OIDC Issuer. If Tailscale is able to retrieve an issuer from your WebFinger endpoint, it will be displayed in the Issuer field.

4. In the Client ID field, enter the ID that is generated for Tailscale by your OIDC provider.

5. In the Client secret field, enter the client secret generated for Tailscale by your OIDC provider.

6. (Optional) In the Prompts field, select one or more prompts to use for the user authentication flow. Note that you are not required to pick a value. These values are defined in the OIDC Authentication Request specification. If you select none, you cannot select any other prompt.

7. Select Sign up with OIDC. You will be redirected to your provider for authentication.

8. Log in to your provider using the email you entered in step 2. Upon authentication, you will be redirected to the Tailscale admin console.

The user that configures OIDC for Tailscale becomes the first user in the tailnet and Owner of the tailnet.

Additional tailnet users

When additional users from the same domain log in to Tailscale, they can enter their email, and will be redirected for authentication to the recognized identity provider.

Migrate an existing tailnet

If you have an existing tailnet, contact support to migrate to a custom OIDC provider. You must have a WebFinger endpoint correctly configured on your domain.

Notes

• Self-hosted identity providers must be publicly accessible on the internet. IP block listing may interfere with the ability to sign up or authenticate to your tailnet.
• User and group provisioning is not supported for custom OIDC provider setups.
• All users connecting to a tailnet from the same domain must use the same identity provider.
• When a user logs out of Tailscale, they are not logged out of their identity provider automatically. If users do not log out of the identity provider, then when they reconnect to Tailscale, they will not need to reauthenticate.
• Tailscale doesn't support Proof Key for Code Exchange (PKCE). Some identity providers enable PKCE by default. If your identity provider enabled PKCE, disable the PKCE feature to avoid errors when installing and running Tailscale.
• JSON Web Encryption (JWE) access tokens are not supported for id_tokens.