Get started
© 2024

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 Connect.


  • 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

  • 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, 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": "",
      "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. Click the search icon.
  4. Examine the results to see 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:

Additional provider configurations

Specific identity providers may require additional configurations:

Identity providerAdditional configurations needed
AutheliaRefer to the instructions in the Authelia topic about Tailscale.
AuthentikUse an RS256 signing token as the signing key.
AWS CognitoNone
GitLabYou must have an active GitLab session in your browser when signing up or in.
GitLab self-managedYou must have an active GitLab session in your browser when signing up or in.
JumpCloudService Provider Attribute Name for email and name mapped to email and fullname as a JumpCloud Attribute Name, and Client Authentication Type set to Client Secret Basic.
Ory NetworkNone
Ory self-hostedNone
Ping IdentityNone
ZITADEL Open SourceNone
ZohoYou must set up a Server-based Applications client type. The Issuer URL for your application must match the data center region the application was created in. As examples, US-based applications must use whereas Canada-based applications must use Your Zoho region is the domain you navigate to in order to view your Zoho Dashboard. If you have users based in different Zoho regions, you must check the Use the same OAuth credentials for all data centers box under the Settings tab for the application.

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.

    Select OIDC when signing up to Tailscale
  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. Click 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. Click 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.

We can only migrate a Tailscale account that uses a custom domain to a custom OIDC provider. For example, can be migrated, while non-custom domains such as cannot be migrated.


  • 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.