{"slug":"custom-oidc-providers","title":"Custom OIDC providers","tags":["tailscale"],"agent_summary":"Last validated: Dec 10, 2025","trigger_phrases":[],"runnable":false,"markdown":"\r\n# Custom OIDC providers\r\n\r\nLast validated: Dec 10, 2025\r\n\r\nTailscale 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](https://openid.net/connect).\r\n\r\n## [Requirements](https://tailscale.com/docs/integrations/identity/custom-oidc\\#requirements)\r\n\r\n- Proof of domain ownership and OIDC discovery using WebFinger.\r\n- An identity provider with SSO based on OIDC, that uses `openid`, `profile`, and `email` scopes, and provides for a callback URL.\r\n- The OIDC provider must use either ES256 or RSA signatures; the minimum RSA key size is 2048 bits.\r\n\r\n## [WebFinger setup](https://tailscale.com/docs/integrations/identity/custom-oidc\\#webfinger-setup)\r\n\r\nTo 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](https://www.rfc-editor.org/rfc/rfc7033.html#section-3.1).\r\n\r\nThe 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:\r\n\r\n```json\r\n{\r\n  \"subject\": \"acct:${email}\",\r\n  \"links\": [\\\r\n    {\\\r\n      \"rel\": \"http://openid.net/specs/connect/1.0/issuer\",\\\r\n      \"href\": \"${issuer URL}\"\\\r\n    }\\\r\n  ]\r\n}\r\n```\r\n\r\nThe 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](https://www.rfc-editor.org/rfc/rfc7033.html#section-3.1) section in the RFC 7033: WebFinger specification.\r\n\r\nTo verify your WebFinger endpoint:\r\n\r\n1. In your browser, open the [WebFinger Lookup tool](https://webfinger.net/lookup).\r\n2. In the **Lookup WebFinger** search box, enter the user's email address.\r\n3. Select the search icon.\r\n4. Examine the results to determine if your endpoint is valid.\r\n\r\nTailscale uses the issuer value from your WebFinger endpoint _only_ during the initial setup. After you have started using a custom OIDC provider with Tailscale, to use a new issuer, update the issue in your WebFinger endpoint and then [contact support](https://tailscale.com/contact/support) so we can finalize your integration with the new issuer.\r\n\r\n## [Identity provider setup](https://tailscale.com/docs/integrations/identity/custom-oidc\\#identity-provider-setup)\r\n\r\nThe identity provider used for your custom OIDC setup must comply with the OIDC specification and the Tailscale requirements.\r\n\r\n**Tailscale** requires you to provide the following:\r\n\r\n- Issuer URL retrieved from the WebFinger endpoint, described in the [previous section](https://tailscale.com/docs/integrations/identity/custom-oidc#webfinger-setup).\r\n- Client ID.\r\n- Client secret from your identity provider.\r\n\r\n**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](https://tailscale.com/privacy-policy).\r\n\r\n**Prompts** specify the requirements and behavior on the authentication page for the user. Prompts are optional, and the supported values within the Tailscale\r\nsetup UI are `none`, `consent` (the default), `login`, and `select_account`. Note that individual identity providers or identity provider\r\nconfiguration may not support any or all of these values. For more information, refer to the OIDC [Authentication Request](https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest) specification.\r\n\r\n**Callback URL** must be configured in your identity provider settings, with the following URL:\r\n\r\n`https://login.tailscale.com/a/oauth_response`\r\n\r\n### [Additional provider configurations](https://tailscale.com/docs/integrations/identity/custom-oidc\\#additional-provider-configurations)\r\n\r\nSpecific identity providers may require additional configurations:\r\n\r\n| Identity provider | Additional configurations needed |\r\n| --- | --- |\r\n| Auth0 | None |\r\n| Authelia | Refer to the instructions in the Authelia topic [Tailscale](https://www.authelia.com/integration/openid-connect/tailscale/). |\r\n| Authentik | Refer to the instructions in the Authentik topic [Integrate with Tailscale](https://integrations.goauthentik.io/networking/tailscale/). |\r\n| AWS Cognito | None |\r\n| Codeberg | None |\r\n| Dex | None |\r\n| Duo | None |\r\n| FoxIDs | Refer to the instructions in the FoxIDs topic [Connect to Tailscale with OpenID Connect](https://www.foxids.com/docs/app-reg-howto-oidc-tailscale). |\r\n| Gitea | None |\r\n| GitLab | You must have an active GitLab session in your browser when signing up or in. |\r\n| GitLab self-managed | You must have an active GitLab session in your browser when signing up or in. |\r\n| JumpCloud | Service 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. |\r\n| Keycloak | None |\r\n| Ory Network | None |\r\n| Ory self-hosted | None |\r\n| Ping Identity | None |\r\n| Pocket ID | None. For details, refer to our YouTube video [Use a custom OIDC and passkeys to log in to Tailscale with Pocket ID](https://youtu.be/sPUkAm7yDlU). |\r\n| ZITADEL Cloud | None |\r\n| ZITADEL Open Source | None |\r\n| Zoho | You 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 `https://accounts.zoho.com` whereas Canada-based applications must use `https://accounts.zohocloud.ca`. Your Zoho region is the domain you use to access 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. |\r\n\r\n## [Tailscale setup](https://tailscale.com/docs/integrations/identity/custom-oidc\\#tailscale-setup)\r\n\r\n1. Go to the [Sign up with OIDC](https://login.tailscale.com/start/oidc) page of the admin console.\r\n\r\nOr, when [signing up for your Tailscale account](https://login.tailscale.com/start), select **Sign up with OIDC**.\r\n![Select OIDC when signing up to Tailscale](https://tailscale.com/_next/image?url=%2F_next%2Fstatic%2Fmedia%2Fsign-up-oidc.b699a417.png&w=1080&q=75)\r\n2. 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.\r\n\r\n3. Select **Get OIDC Issuer**. If Tailscale is able to retrieve an issuer from your WebFinger endpoint, it will be displayed in the **Issuer** field.\r\n\r\n4. In the **Client ID** field, enter the ID that is generated for Tailscale by your OIDC provider.\r\n\r\n5. In the **Client secret** field, enter the client secret generated for Tailscale by your OIDC provider.\r\n\r\n6. (Optional) In the **Prompts** field, select one or more prompts to use for the user\r\nauthentication flow. Note that you are not required to pick a value. These values are defined in\r\nthe OIDC [Authentication Request](https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest) specification. If you select `none`, you\r\ncannot select any other prompt.\r\n\r\n7. Select **Sign up with OIDC**. You will be redirected to your provider for authentication.\r\n\r\n8. Log in to your provider using the email you entered in step 2. Upon authentication, you will be redirected to the Tailscale admin console.\r\n\r\n\r\nThe user that configures OIDC for Tailscale becomes the first user in the [tailnet](https://tailscale.com/docs/reference/glossary#tailnet) and [Owner](https://tailscale.com/docs/reference/user-roles) of the tailnet.\r\n\r\n## [Additional tailnet users](https://tailscale.com/docs/integrations/identity/custom-oidc\\#additional-tailnet-users)\r\n\r\nWhen 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.\r\n\r\n## [Migrate an existing tailnet](https://tailscale.com/docs/integrations/identity/custom-oidc\\#migrate-an-existing-tailnet)\r\n\r\nIf you have an existing tailnet, [contact support](https://tailscale.com/contact/support) to migrate to a custom OIDC provider. You must have a WebFinger endpoint correctly configured on your domain.\r\n\r\nWe can only migrate a Tailscale account that uses a custom domain to a custom OIDC provider. For example, `@yourcustomdomain.com` can be migrated, while non-custom domains such as `@gmail.com` cannot be migrated.\r\n\r\n## [Notes](https://tailscale.com/docs/integrations/identity/custom-oidc\\#notes)\r\n\r\n- 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.\r\n- User and group provisioning is not supported for custom OIDC provider setups.\r\n- All users connecting to a tailnet from the same domain must use the same identity provider.\r\n- 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.\r\n- Tailscale doesn't support [Proof Key for Code Exchange](https://www.rfc-editor.org/rfc/rfc7636.html) (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.\r\n- JSON Web Encryption (JWE) access tokens are not supported for `id_tokens`.\r\n\r\n![Project Logo](https://cdn.brandfetch.io/tailscale.com/fallback/lettermark/theme/dark/h/256/w/256/icon?c=1bfwsmEH20zzEfSNTed)\r\n\r\nAsk AI\r\n\r\nreCAPTCHA\r\n\r\nRecaptcha requires verification.\r\n\r\nprotected by **reCAPTCHA**\r\n","html":"<h1>Custom OIDC providers</h1>\n<p>Last validated: Dec 10, 2025</p>\n<p>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 <a href=\"https://openid.net/connect\">Welcome to OpenID Connect</a>.</p>\n<h2><a href=\"https://tailscale.com/docs/integrations/identity/custom-oidc#requirements\">Requirements</a></h2>\n<ul>\n<li>Proof of domain ownership and OIDC discovery using WebFinger.</li>\n<li>An identity provider with SSO based on OIDC, that uses <code>openid</code>, <code>profile</code>, and <code>email</code> scopes, and provides for a callback URL.</li>\n<li>The OIDC provider must use either ES256 or RSA signatures; the minimum RSA key size is 2048 bits.</li>\n</ul>\n<h2><a href=\"https://tailscale.com/docs/integrations/identity/custom-oidc#webfinger-setup\">WebFinger setup</a></h2>\n<p>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 <a href=\"https://www.rfc-editor.org/rfc/rfc7033.html#section-3.1\">RFC 7033</a>.</p>\n<p>The WebFinger endpoint must be served at <code>https://${domain}/.well-known/webfinger</code> and must include the issuer URL within the JRD in the response. For example:</p>\n<pre><code class=\"language-json\">{\r\n  \"subject\": \"acct:${email}\",\r\n  \"links\": [\\\r\n    {\\\r\n      \"rel\": \"http://openid.net/specs/connect/1.0/issuer\",\\\r\n      \"href\": \"${issuer URL}\"\\\r\n    }\\\r\n  ]\r\n}\n</code></pre>\n<p>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 <code>/.well-known/openid-configuration</code>. For more information, refer to the <a href=\"https://www.rfc-editor.org/rfc/rfc7033.html#section-3.1\">Identity Provider Discovery for OpenID Connect</a> section in the RFC 7033: WebFinger specification.</p>\n<p>To verify your WebFinger endpoint:</p>\n<ol>\n<li>In your browser, open the <a href=\"https://webfinger.net/lookup\">WebFinger Lookup tool</a>.</li>\n<li>In the <strong>Lookup WebFinger</strong> search box, enter the user's email address.</li>\n<li>Select the search icon.</li>\n<li>Examine the results to determine if your endpoint is valid.</li>\n</ol>\n<p>Tailscale uses the issuer value from your WebFinger endpoint <em>only</em> during the initial setup. After you have started using a custom OIDC provider with Tailscale, to use a new issuer, update the issue in your WebFinger endpoint and then <a href=\"https://tailscale.com/contact/support\">contact support</a> so we can finalize your integration with the new issuer.</p>\n<h2><a href=\"https://tailscale.com/docs/integrations/identity/custom-oidc#identity-provider-setup\">Identity provider setup</a></h2>\n<p>The identity provider used for your custom OIDC setup must comply with the OIDC specification and the Tailscale requirements.</p>\n<p><strong>Tailscale</strong> requires you to provide the following:</p>\n<ul>\n<li>Issuer URL retrieved from the WebFinger endpoint, described in the <a href=\"https://tailscale.com/docs/integrations/identity/custom-oidc#webfinger-setup\">previous section</a>.</li>\n<li>Client ID.</li>\n<li>Client secret from your identity provider.</li>\n</ul>\n<p><strong>Scopes</strong> specify the required information to include in the authentication request. The required scopes are <code>openid</code>, <code>profile</code>, and <code>email</code>. Tailscale requests the minimum number scopes required to operate, and the information on how we use your data can be found in our <a href=\"https://tailscale.com/privacy-policy\">privacy policy</a>.</p>\n<p><strong>Prompts</strong> specify the requirements and behavior on the authentication page for the user. Prompts are optional, and the supported values within the Tailscale\r\nsetup UI are <code>none</code>, <code>consent</code> (the default), <code>login</code>, and <code>select_account</code>. Note that individual identity providers or identity provider\r\nconfiguration may not support any or all of these values. For more information, refer to the OIDC <a href=\"https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest\">Authentication Request</a> specification.</p>\n<p><strong>Callback URL</strong> must be configured in your identity provider settings, with the following URL:</p>\n<p><code>https://login.tailscale.com/a/oauth_response</code></p>\n<h3><a href=\"https://tailscale.com/docs/integrations/identity/custom-oidc#additional-provider-configurations\">Additional provider configurations</a></h3>\n<p>Specific identity providers may require additional configurations:</p>\n<p>| Identity provider | Additional configurations needed |\r\n| --- | --- |\r\n| Auth0 | None |\r\n| Authelia | Refer to the instructions in the Authelia topic <a href=\"https://www.authelia.com/integration/openid-connect/tailscale/\">Tailscale</a>. |\r\n| Authentik | Refer to the instructions in the Authentik topic <a href=\"https://integrations.goauthentik.io/networking/tailscale/\">Integrate with Tailscale</a>. |\r\n| AWS Cognito | None |\r\n| Codeberg | None |\r\n| Dex | None |\r\n| Duo | None |\r\n| FoxIDs | Refer to the instructions in the FoxIDs topic <a href=\"https://www.foxids.com/docs/app-reg-howto-oidc-tailscale\">Connect to Tailscale with OpenID Connect</a>. |\r\n| Gitea | None |\r\n| GitLab | You must have an active GitLab session in your browser when signing up or in. |\r\n| GitLab self-managed | You must have an active GitLab session in your browser when signing up or in. |\r\n| JumpCloud | Service Provider Attribute Name for <code>email</code> and <code>name</code> mapped to <code>email</code> and <code>fullname</code> as a JumpCloud Attribute Name, and Client Authentication Type set to Client Secret Basic. |\r\n| Keycloak | None |\r\n| Ory Network | None |\r\n| Ory self-hosted | None |\r\n| Ping Identity | None |\r\n| Pocket ID | None. For details, refer to our YouTube video <a href=\"https://youtu.be/sPUkAm7yDlU\">Use a custom OIDC and passkeys to log in to Tailscale with Pocket ID</a>. |\r\n| ZITADEL Cloud | None |\r\n| ZITADEL Open Source | None |\r\n| Zoho | You 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 <code>https://accounts.zoho.com</code> whereas Canada-based applications must use <code>https://accounts.zohocloud.ca</code>. Your Zoho region is the domain you use to access your Zoho Dashboard. If you have users based in different Zoho regions, you must check the <strong>Use the same OAuth credentials for all data centers</strong> box under the <strong>Settings</strong> tab for the application. |</p>\n<h2><a href=\"https://tailscale.com/docs/integrations/identity/custom-oidc#tailscale-setup\">Tailscale setup</a></h2>\n<ol>\n<li>Go to the <a href=\"https://login.tailscale.com/start/oidc\">Sign up with OIDC</a> page of the admin console.</li>\n</ol>\n<p>Or, when <a href=\"https://login.tailscale.com/start\">signing up for your Tailscale account</a>, select <strong>Sign up with OIDC</strong>.\r\n<img src=\"https://tailscale.com/_next/image?url=%2F_next%2Fstatic%2Fmedia%2Fsign-up-oidc.b699a417.png&#x26;w=1080&#x26;q=75\" alt=\"Select OIDC when signing up to Tailscale\">\r\n2. In the <strong>Email address</strong> 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.</p>\n<ol start=\"3\">\n<li>\n<p>Select <strong>Get OIDC Issuer</strong>. If Tailscale is able to retrieve an issuer from your WebFinger endpoint, it will be displayed in the <strong>Issuer</strong> field.</p>\n</li>\n<li>\n<p>In the <strong>Client ID</strong> field, enter the ID that is generated for Tailscale by your OIDC provider.</p>\n</li>\n<li>\n<p>In the <strong>Client secret</strong> field, enter the client secret generated for Tailscale by your OIDC provider.</p>\n</li>\n<li>\n<p>(Optional) In the <strong>Prompts</strong> field, select one or more prompts to use for the user\r\nauthentication flow. Note that you are not required to pick a value. These values are defined in\r\nthe OIDC <a href=\"https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest\">Authentication Request</a> specification. If you select <code>none</code>, you\r\ncannot select any other prompt.</p>\n</li>\n<li>\n<p>Select <strong>Sign up with OIDC</strong>. You will be redirected to your provider for authentication.</p>\n</li>\n<li>\n<p>Log in to your provider using the email you entered in step 2. Upon authentication, you will be redirected to the Tailscale admin console.</p>\n</li>\n</ol>\n<p>The user that configures OIDC for Tailscale becomes the first user in the <a href=\"https://tailscale.com/docs/reference/glossary#tailnet\">tailnet</a> and <a href=\"https://tailscale.com/docs/reference/user-roles\">Owner</a> of the tailnet.</p>\n<h2><a href=\"https://tailscale.com/docs/integrations/identity/custom-oidc#additional-tailnet-users\">Additional tailnet users</a></h2>\n<p>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.</p>\n<h2><a href=\"https://tailscale.com/docs/integrations/identity/custom-oidc#migrate-an-existing-tailnet\">Migrate an existing tailnet</a></h2>\n<p>If you have an existing tailnet, <a href=\"https://tailscale.com/contact/support\">contact support</a> to migrate to a custom OIDC provider. You must have a WebFinger endpoint correctly configured on your domain.</p>\n<p>We can only migrate a Tailscale account that uses a custom domain to a custom OIDC provider. For example, <code>@yourcustomdomain.com</code> can be migrated, while non-custom domains such as <code>@gmail.com</code> cannot be migrated.</p>\n<h2><a href=\"https://tailscale.com/docs/integrations/identity/custom-oidc#notes\">Notes</a></h2>\n<ul>\n<li>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.</li>\n<li>User and group provisioning is not supported for custom OIDC provider setups.</li>\n<li>All users connecting to a tailnet from the same domain must use the same identity provider.</li>\n<li>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.</li>\n<li>Tailscale doesn't support <a href=\"https://www.rfc-editor.org/rfc/rfc7636.html\">Proof Key for Code Exchange</a> (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.</li>\n<li>JSON Web Encryption (JWE) access tokens are not supported for <code>id_tokens</code>.</li>\n</ul>\n<p><img src=\"https://cdn.brandfetch.io/tailscale.com/fallback/lettermark/theme/dark/h/256/w/256/icon?c=1bfwsmEH20zzEfSNTed\" alt=\"Project Logo\"></p>\n<p>Ask AI</p>\n<p>reCAPTCHA</p>\n<p>Recaptcha requires verification.</p>\n<p>protected by <strong>reCAPTCHA</strong></p>\n"}