<!doctype html><htmllang=enclass=no-js><head><metacharset=utf-8><metaname=viewportcontent="width=device-width,initial-scale=1"><metaname=descriptioncontent="An open source, self-hosted implementation of the Tailscale control server."><metaname=authorcontent="Headscale authors"><linkhref=https://juanfont.github.io/headscale/development/ref/oidc/rel=canonical><linkhref=../configuration/rel=prev><linkhref=../routes/rel=next><linkrel=iconhref=../../assets/favicon.png><metaname=generatorcontent="mkdocs-1.6.1, mkdocs-material-9.6.16"><title>OpenID Connect - Headscale</title><linkrel=stylesheethref=../../assets/stylesheets/main.7e37652d.min.css><linkrel=stylesheethref=../../assets/stylesheets/palette.06af60db.min.css><linkrel=preconnecthref=https://fonts.gstatic.comcrossorigin><linkrel=stylesheethref="https://fonts.googleapis.com/css?family=Roboto:300,300i,400,400i,700,700i%7CRoboto+Mono:400,400i,700,700i&display=fallback"><style>:root{--md-text-font:"Roboto";--md-code-font:"Roboto Mono"}</style><script>__md_scope=newURL("../..",location),__md_hash=e=>[...e].reduce(((e,_)=>(e<<5)-e+_.charCodeAt(0)),0),__md_get=(e,_=localStorage,t=__md_scope)=>JSON.parse(_.getItem(t.pathname+"."+e)),__md_set=(e,_,t=localStorage,a=__md_scope)=>{try{t.setItem(a.pathname+"."+e,JSON.stringify(_))}catch(e){}}</script><metaproperty=og:typecontent=website><metaproperty=og:titlecontent="OpenID Connect - Headscale"><metaproperty=og:descriptioncontent="An open source, self-hosted implementation of the Tailscale control server."><metaproperty=og:imagecontent=https://juanfont.github.io/headscale/development/assets/images/social/ref/oidc.png><metaproperty=og:image:typecontent=image/png><metaproperty=og:image:widthcontent=1200><metaproperty=og:image:heightcontent=630><metacontent=https://juanfont.github.io/headscale/development/ref/oidc/property=og:url><metaname=twitter:cardcontent=summary_large_image><metaname=twitter:titlecontent="OpenID Connect - Headscale"><metaname=twitter:descriptioncontent="An open source, self-hosted implementation of the Tailscale control server."><metaname=twitter:imagecontent=https://juanfont.github.io/headscale/development/assets/images/social/ref/oidc.png></head><bodydir=ltrdata-md-color-scheme=defaultdata-md-color-primary=whitedata-md-color-accent=indigo><inputclass=md-toggledata-md-toggle=drawertype=checkboxid=__drawerautocomplete=off><inputclass=md-toggledata-md-toggle=searchtype=checkboxid=__searchautocomplete=off><labelclass=md-overlayfor=__drawer></label><divdata-md-component=skip><ahref=#openid-connectclass=md-skip> Skip to content </a></div><divdata-md-component=announce></div><divdata-md-color-scheme=defaultdata-md-component=outdatedhidden></div><headerclass=md-headerdata-md-component=header><navclass="md-header__inner md-grid"aria-label=Header><ahref=../..title=Headscaleclass="md-header__button md-logo"aria-label=Headscaledata-md-component=logo><imgsrc=../../logo/headscale3-dots.svgalt=logo></a><labelclass="md-header__button md-icon"for=__drawer><svgxmlns=http://www.w3.org/2000/svgviewbox="0 0 24 24"><pathd="M3 6h18v2H3zm0 5h18v2H3zm0 5h18v2H3z"/></svg></label><divclass=md-header__titledata-md-component=header-title><divclass=md-header__ellipsis><divclass=md-header__topic><spanclass=md-ellipsis> Headscale </span></div><divclass=md-header__topicdata-md-component=header-topic><spanclass=md-ellipsis> OpenID Connect </span></div></div></div><formclass=md-header__optiondata-md-component=palette><inputclass=md-optiondata-md-color-mediadata-md-color-scheme=defaultdata-md-color-primary=whitedata-md-color-accent=indigoaria-label="Switch to dark mode"type=radioname=__paletteid=__palette_0><labelclass="md-header__button md-icon"title="Switch to dark mode"for=__palette_1hidden><svgxmlns=http://www.w3.org/2000/svgviewbox="0 0 24 24"><pathd="M128a44000-444400044440004-444000-4-4m010a66001-6-6660016-6660016666001-66m8-9.31V4h-4.69L12.69
</span></code></pre></div></div><divclass=tabbed-block><ul><li>Create a new confidential client (<code>Client ID</code>, <code>Client secret</code>)</li><li>Add Headscale's OIDC callback URL as valid redirect URL: <code>https://headscale.example.com/oidc/callback</code></li><li>Configure additional parameters to improve user experience such as: name, description, logo, …</li></ul></div></div></div><h3id=enable-pkce-recommended>Enable PKCE (recommended)<aclass=headerlinkhref=#enable-pkce-recommendedtitle="Permanent link">¶</a></h3><p>Proof Key for Code Exchange (PKCE) adds an additional layer of security to the OAuth 2.0 authorization code flow by preventing authorization code interception attacks, see: <ahref=https://datatracker.ietf.org/doc/html/rfc7636>https://datatracker.ietf.org/doc/html/rfc7636</a>. PKCE is recommended and needs to be configured for Headscale and the identity provider alike:</p><divclass="tabbed-set tabbed-alternate"data-tabs=2:2><inputchecked=checkedid=__tabbed_2_1name=__tabbed_2type=radio><inputid=__tabbed_2_2name=__tabbed_2type=radio><divclass=tabbed-labels><labelfor=__tabbed_2_1>Headscale</label><labelfor=__tabbed_2_2>Identity provider</label></div><divclass=tabbed-content><divclass=tabbed-block><divclass="language-yaml highlight"><pre><span></span><code><spanid=__span-1-1><aid=__codelineno-1-1name=__codelineno-1-1href=#__codelineno-1-1></a><spanclass=nt>oidc</span><spanclass=p>:</span>
</span></span></code></pre></div></div><divclass=tabbed-block><ul><li>Enable PKCE for the headscale client</li><li>Set the PKCE challenge method to "S256"</li></ul></div></div></div><h3id=authorize-users-with-filters>Authorize users with filters<aclass=headerlinkhref=#authorize-users-with-filterstitle="Permanent link">¶</a></h3><p>Headscale allows to filter for allowed users based on their domain, email address or group membership. These filters can be helpful to apply additional restrictions and control which users are allowed to join. Filters are disabled by default, users are allowed to join once the authentication with the identity provider succeeds. In case multiple filters are configured, a user needs to pass all of them.</p><divclass="tabbed-set tabbed-alternate"data-tabs=3:3><inputchecked=checkedid=__tabbed_3_1name=__tabbed_3type=radio><inputid=__tabbed_3_2name=__tabbed_3type=radio><inputid=__tabbed_3_3name=__tabbed_3type=radio><divclass=tabbed-labels><labelfor=__tabbed_3_1>Allowed domains</label><labelfor=__tabbed_3_2>Allowed users/emails</label><labelfor=__tabbed_3_3>Allowed groups</label></div><divclass=tabbed-content><divclass=tabbed-block><ul><li>Check the email domain of each authenticating user against the list of allowed domains and only authorize users whose email domain matches <code>example.com</code>.</li><li>Access allowed: <code>alice@example.com</code></li><li>Access denied: <code>bob@example.net</code></li></ul><divclass="language-yaml highlight"><pre><span></span><code><spanid=__span-2-1><aid=__codelineno-2-1name=__codelineno-2-1href=#__codelineno-2-1></a><spanclass=nt>oidc</span><spanclass=p>:</span>
</span></span></code></pre></div></div><divclass=tabbed-block><ul><li>Check the email address of each authenticating user against the list of allowed email addresses and only authorize users whose email is part of the <code>allowed_users</code> list.</li><li>Access allowed: <code>alice@example.com</code>, <code>bob@example.net</code></li><li>Access denied: <code>mallory@example.net</code></li></ul><divclass="language-yaml highlight"><pre><span></span><code><spanid=__span-3-1><aid=__codelineno-3-1name=__codelineno-3-1href=#__codelineno-3-1></a><spanclass=nt>oidc</span><spanclass=p>:</span>
</span></span></code></pre></div></div><divclass=tabbed-block><ul><li>Use the OIDC <code>groups</code> claim of each authenticating user to get their group membership and only authorize users which are members in at least one of the referenced groups.</li><li>Access allowed: users in the <code>headscale_users</code> group</li><li>Access denied: users without groups, users with other groups</li></ul><divclass="language-yaml highlight"><pre><span></span><code><spanid=__span-4-1><aid=__codelineno-4-1name=__codelineno-4-1href=#__codelineno-4-1></a><spanclass=nt>oidc</span><spanclass=p>:</span>
</span></span></code></pre></div></div></div></div><h3id=customize-node-expiration>Customize node expiration<aclass=headerlinkhref=#customize-node-expirationtitle="Permanent link">¶</a></h3><p>The node expiration is the amount of time a node is authenticated with OpenID Connect until it expires and needs to reauthenticate. The default node expiration is 180 days. This can either be customized or set to the expiration from the Access Token.</p><divclass="tabbed-set tabbed-alternate"data-tabs=4:2><inputchecked=checkedid=__tabbed_4_1name=__tabbed_4type=radio><inputid=__tabbed_4_2name=__tabbed_4type=radio><divclass=tabbed-labels><labelfor=__tabbed_4_1>Customize node expiration</label><labelfor=__tabbed_4_2>Use expiration from Access Token</label></div><divclass=tabbed-content><divclass=tabbed-block><divclass="language-yaml highlight"><pre><span></span><code><spanid=__span-5-1><aid=__codelineno-5-1name=__codelineno-5-1href=#__codelineno-5-1></a><spanclass=nt>oidc</span><spanclass=p>:</span>
</span><spanid=__span-5-5><aid=__codelineno-5-5name=__codelineno-5-5href=#__codelineno-5-5></a><spanclass=hll><spanclass=w></span><spanclass=nt>expiry</span><spanclass=p>:</span><spanclass=w></span><spanclass="l l-Scalar l-Scalar-Plain">30d</span><spanclass=w></span><spanclass=c1># Use 0 to disable node expiration</span>
</span></span></code></pre></div></div><divclass=tabbed-block><p>Please keep in mind that the Access Token is typically a short-lived token that expires within a few minutes. You will have to configure token expiration in your identity provider to avoid frequent re-authentication.</p><divclass="language-yaml highlight"><pre><span></span><code><spanid=__span-6-1><aid=__codelineno-6-1name=__codelineno-6-1href=#__codelineno-6-1></a><spanclass=nt>oidc</span><spanclass=p>:</span>
</span></span></code></pre></div></div></div></div><divclass="admonition tip"><pclass=admonition-title>Expire a node and force re-authentication</p><p>A node can be expired immediately via: <divclass="language-console highlight"><pre><span></span><code><spanid=__span-7-1><aid=__codelineno-7-1name=__codelineno-7-1href=#__codelineno-7-1></a><spanclass=go>headscale node expire -i <NODE_ID></span>
</span></code></pre></div></p></div><h3id=reference-a-user-in-the-policy>Reference a user in the policy<aclass=headerlinkhref=#reference-a-user-in-the-policytitle="Permanent link">¶</a></h3><p>You may refer to users in the Headscale policy via:</p><ul><li>Email address</li><li>Username</li><li>Provider identifier (only available in the database or from your identity provider)</li></ul><divclass="admonition note"><pclass=admonition-title>A user identifier in the policy must contain a single <code>@</code></p><p>The Headscale policy requires a single <code>@</code> to reference a user. If the username or provider identifier doesn't already contain a single <code>@</code>, it needs to be appended at the end. For example: the username <code>ssmith</code> has to be written as <code>ssmith@</code> to be correctly identified as user within the policy.</p></div><divclass="admonition warning"><pclass=admonition-title>Email address or username might be updated by users</p><p>Many identity providers allow users to update their own profile. Depending on the identity provider and its configuration, the values for username or email address might change over time. This might have unexpected consequences for Headscale where a policy might no longer work or a user might obtain more access by hijacking an existing username or email address.</p></div><h2id=supported-oidc-claims>Supported OIDC claims<aclass=headerlinkhref=#supported-oidc-claimstitle="Permanent link">¶</a></h2><p>Headscale uses <ahref=https://openid.net/specs/openid-connect-core-1_0.html#StandardClaims>the standard OIDC claims</a> to populate and update its local user profile on each login. OIDC claims are read from the ID Token or from the UserInfo endpoint.</p><table><thead><tr><th>Headscale profile</th><th>OIDC claim</th><th>Notes / examples</th></tr></thead><tbody><tr><td>email address</td><td><code>email</code></td><td>Only used when <code>email_verified: true</code></td></tr><tr><td>display name</td><td><code>name</code></td><td>eg: <code>Sam Smith</code></td></tr><tr><td>username</td><td><code>preferred_username</code></td><td>Depends on identity provider, eg: <code>ssmith</code>, <code>ssmith@idp.example.com</code>, <code>\\example.com\ssmith</code></td></tr><tr><td>profile picture</td><td><code>picture</code></td><td>URL to a profile picture or avatar</td></tr><tr><td>provider identifier</td><td><code>iss</code>, <code>sub</code></td><td>A stable and unique identifier for a user, typically a combination of <code>iss</code> and <code>sub</code> OIDC claims</td></tr><tr><td></td><td><code>groups</code></td><td><ahref=#authorize-users-with-filters>Only used to filter for allowed groups</a></td></tr></tbody></table><h2id=limitations>Limitations<aclass=headerlinkhref=#limitationstitle="Permanent link">¶</a></h2><ul><li>Support for OpenID Connect aims to be generic and vendor independent. It offers only limited support for quirks of specific identity providers.</li><li>OIDC groups cannot be used in ACLs.</li><li>The username provided by the identity provider needs to adhere to this pattern:<ul><li>The username must be at least two characters long.</li><li>It must only contain letters, digits, hyphens, dots, underscores, and up to a single <code>@</code>.</li><li>The username must start with a letter.</li></ul></li><li>A user's email address is only synchronized to the local user profile when the identity provider marks the email address as verified (<code>email_verified: true</code>).</li></ul><p>Please see the <ahref=https://github.com/juanfont/headscale/labels/OIDC>GitHub label "OIDC"</a> for OIDC related issues.</p><h2id=identity-provider-specific-configuration>Identity provider specific configuration<aclass=headerlinkhref=#identity-provider-specific-configurationtitle="Permanent link">¶</a></h2><divclass="admonition warning"><pclass=admonition-title>Third-party software and services</p><p>This section of the documentation is specific for third-part
