Custom OIDC providers

Tailscale can integrate with identity providers that support OpenID Connect (OIDC). The steps provided in this article 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, see Welcome to OpenID Connnect.

Requirements

Proof of domain ownership and OIDC discovery using WebFinger
An identity provider with SSO via OIDC, that uses openid, profile, and email scopes, and provides for a callback URL

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, see 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.

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. During authentication, Tailscale will request the consent prompt. Note that individual identity providers or identity provider configuration may or may not support this.

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:

Identity provider	Additional configurations needed
Auth0	None
Authelia	Refer to the instructions in the Authelia topic about Tailscale.
Authentik	Use an `RS256` signing token as the signing key
Dex	None
Duo	None
GitLab	You must have an active GitLab session in your browser when signing up or in
GitLab self-managed	You must have an active GitLab session in your browser when signing up or in
JumpCloud	Service Provider Attribute Name for `email` and `name` mapped to `email` and `fullname` as a JumpCloud Attribute Name's
Keycloak	None
Ory Network	None
Ory self-hosted	None
ZITADEL Cloud	None
ZITADEL Open Source	None

Tailscale setup

Go to the Sign up with OIDC page of the admin console.
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.
Click Get OIDC Issuer. If Tailscale is able to retrieve an issuer from your WebFinger endpoint, it will be displayed in the Issuer field.
In the Client ID field, enter the ID that is generated for Tailscale by your OIDC provider.
In the Client secret field, enter the client secret generated for Tailscale by your OIDC provider.
Click Sign up with OIDC. You will be redirected to your provider for authentication.
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.

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.