mirror of
https://github.com/juanfont/headscale.git
synced 2026-10-28 17:26:52 +09:00
Deployed a2b1d786 to 0.29.6 with ProperDocs 1.6.7 and mike 2.2.0
This commit is contained in:
1 parent
ec9e2d90d3
commit
b8ec0f1b59
105 files changed
+1210
-6
No files matched your search
@@ -0,0 +1,61 @@
|
||||
<!doctype html><html lang=en class=no-js> <head><meta charset=utf-8><meta name=viewport content="width=device-width,initial-scale=1"><meta name=description content="An open source, self-hosted implementation of the Tailscale control server."><meta name=author content="Headscale authors"><link href=https://juanfont.github.io/headscale/0.29.6/ref/oidc/ rel=canonical><link href=../registration/ rel=prev><link href=../routes/ rel=next><link rel=icon href=../../assets/favicon.png><meta name=generator content="mkdocs-ProperDocs 1.6.7, mkdocs-materialx-10.2.2"><title>OpenID Connect - Headscale</title><link rel=stylesheet href=../../assets/stylesheets/main.1d60cbd7.min.css><link rel=stylesheet href=../../assets/stylesheets/palette.a45159b5.min.css><link rel=preconnect href=https://fonts.gstatic.com crossorigin><link rel=stylesheet href="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=new URL("../..",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><meta property=og:type content=website><meta property=og:title content="OpenID Connect - Headscale"><meta property=og:description content="An open source, self-hosted implementation of the Tailscale control server."><meta property=og:image content=https://juanfont.github.io/headscale/0.29.6/assets/images/social/ref/oidc.png><meta property=og:image:type content=image/png><meta property=og:image:width content=1200><meta property=og:image:height content=630><meta content=https://juanfont.github.io/headscale/0.29.6/ref/oidc/ property=og:url><meta property=twitter:card content=summary_large_image><meta property=twitter:title content="OpenID Connect - Headscale"><meta property=twitter:description content="An open source, self-hosted implementation of the Tailscale control server."><meta property=twitter:image content=https://juanfont.github.io/headscale/0.29.6/assets/images/social/ref/oidc.png></head> <body dir=ltr data-md-color-scheme=default data-md-color-primary=indigo data-md-color-accent=indigo data-mx-topbar=glass> <input class=md-toggle data-md-toggle=drawer type=checkbox id=__drawer autocomplete=off> <input class=md-toggle data-md-toggle=toc type=checkbox id=__toc autocomplete=off> <input class=md-toggle data-md-toggle=search type=checkbox id=__search autocomplete=off> <label class=md-overlay for=__drawer></label> <label class=md-overlay for=__toc></label> <div data-md-component=skip> <a href=#openid-connect class=md-skip> Skip to content </a> </div> <div data-md-component=announce> </div> <div data-md-color-scheme=default data-md-component=outdated hidden> </div> <header class=md-header data-md-component=header> <nav class="md-header__inner md-grid" aria-label=Header> <a href=../.. title=Headscale class="md-header__button md-logo" aria-label=Headscale data-md-component=logo> <img src=../../assets/logo/headscale3-dots.svg alt=logo> </a> <label class="md-header__button md-icon" for=__drawer> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M3 6h18v2H3zm0 5h18v2H3zm0 5h18v2H3z"/></svg> </label> <div class=md-header__title data-md-component=header-title> <div class=md-header__ellipsis> <div class=md-header__topic> <span class=md-ellipsis> Headscale </span> </div> <div class=md-header__topic data-md-component=header-topic> <span class=md-ellipsis> OpenID Connect </span> </div> </div> </div> <form class=md-header__option data-md-component=palette> <input class=md-option data-md-color-media=(prefers-color-scheme) data-md-color-scheme=default data-md-color-primary=indigo data-md-color-accent=indigo aria-label="Switch to light mode" type=radio name=__palette id=__palette_0> <label class="md-header__button md-icon" title="Switch to light mode" for=__palette_1 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="m14.3 16-.7-2h-3.2l-.7 2H7.8L11 7h2l3.2 9zM20 8.69V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12zm-9.15 3.96h2.3L12 9z"/></svg> </label> <input class=md-option data-md-color-media="(prefers-color-scheme: light)" data-md-color-scheme=default data-md-color-primary=indigo data-md-color-accent=indigo aria-label="Switch to dark mode" type=radio name=__palette id=__palette_1> <label class="md-header__button md-icon" title="Switch to dark mode" for=__palette_2 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 8a4 4 0 0 0-4 4 4 4 0 0 0 4 4 4 4 0 0 0 4-4 4 4 0 0 0-4-4m0 10a6 6 0 0 1-6-6 6 6 0 0 1 6-6 6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> <input class=md-option data-md-color-media="(preLine truncated
|
||||
</span><span id=__span-0-2><a id=__codelineno-0-2 name=__codelineno-0-2 href=#__codelineno-0-2></a><span class=w> </span><span class=nt>issuer</span><span class=p>:</span><span class=w> </span><span class=s>"https://sso.example.com"</span>
|
||||
</span><span id=__span-0-3><a id=__codelineno-0-3 name=__codelineno-0-3 href=#__codelineno-0-3></a><span class=w> </span><span class=nt>client_id</span><span class=p>:</span><span class=w> </span><span class=s>"headscale"</span>
|
||||
</span><span id=__span-0-4><a id=__codelineno-0-4 name=__codelineno-0-4 href=#__codelineno-0-4></a><span class=w> </span><span class=nt>client_secret</span><span class=p>:</span><span class=w> </span><span class=s>"generated-secret"</span>
|
||||
</span></code></pre></div> </div> <div class=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> <h3 id=enable-pkce-recommended>Enable PKCE (recommended)<a class=headerlink href=#enable-pkce-recommended title="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: <a href=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> <div class="tabbed-set tabbed-alternate" data-tabs=2:2><input checked=checked id=__tabbed_2_1 name=__tabbed_2 type=radio><input id=__tabbed_2_2 name=__tabbed_2 type=radio><div class=tabbed-labels><label for=__tabbed_2_1>Headscale</label><label for=__tabbed_2_2>Identity provider</label></div> <div class=tabbed-content> <div class=tabbed-block> <div class="language-yaml highlight"><pre><span></span><code><span id=__span-1-1><a id=__codelineno-1-1 name=__codelineno-1-1 href=#__codelineno-1-1></a><span class=nt>oidc</span><span class=p>:</span>
|
||||
</span><span id=__span-1-2><a id=__codelineno-1-2 name=__codelineno-1-2 href=#__codelineno-1-2></a><span class=w> </span><span class=nt>issuer</span><span class=p>:</span><span class=w> </span><span class=s>"https://sso.example.com"</span>
|
||||
</span><span id=__span-1-3><a id=__codelineno-1-3 name=__codelineno-1-3 href=#__codelineno-1-3></a><span class=w> </span><span class=nt>client_id</span><span class=p>:</span><span class=w> </span><span class=s>"headscale"</span>
|
||||
</span><span id=__span-1-4><a id=__codelineno-1-4 name=__codelineno-1-4 href=#__codelineno-1-4></a><span class=w> </span><span class=nt>client_secret</span><span class=p>:</span><span class=w> </span><span class=s>"generated-secret"</span>
|
||||
</span><span id=__span-1-5><a id=__codelineno-1-5 name=__codelineno-1-5 href=#__codelineno-1-5></a><span class=hll><span class=w> </span><span class=nt>pkce</span><span class=p>:</span>
|
||||
</span></span><span id=__span-1-6><a id=__codelineno-1-6 name=__codelineno-1-6 href=#__codelineno-1-6></a><span class=hll><span class=w> </span><span class=nt>enabled</span><span class=p>:</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">true</span>
|
||||
</span></span></code></pre></div> </div> <div class=tabbed-block> <ul> <li>Enable PKCE for the headscale client</li> <li>Set the PKCE challenge method to "S256"</li> </ul> </div> </div> </div> <h3 id=authorize-users-with-filters>Authorize users with filters<a class=headerlink href=#authorize-users-with-filters title="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> <div class="tabbed-set tabbed-alternate" data-tabs=3:3><input checked=checked id=__tabbed_3_1 name=__tabbed_3 type=radio><input id=__tabbed_3_2 name=__tabbed_3 type=radio><input id=__tabbed_3_3 name=__tabbed_3 type=radio><div class=tabbed-labels><label for=__tabbed_3_1>Allowed domains</label><label for=__tabbed_3_2>Allowed users/emails</label><label for=__tabbed_3_3>Allowed groups</label></div> <div class=tabbed-content> <div class=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>A verified email address is required <a href=#control-email-verification>unless email verification is disabled</a>.</li> <li>Access allowed: <code>alice@example.com</code></li> <li>Access denied: <code>bob@example.net</code></li> </ul> <div class="language-yaml highlight"><pre><span></span><code><span id=__span-2-1><a id=__codelineno-2-1 name=__codelineno-2-1 href=#__codelineno-2-1></a><span class=nt>oidc</span><span class=p>:</span>
|
||||
</span><span id=__span-2-2><a id=__codelineno-2-2 name=__codelineno-2-2 href=#__codelineno-2-2></a><span class=w> </span><span class=nt>issuer</span><span class=p>:</span><span class=w> </span><span class=s>"https://sso.example.com"</span>
|
||||
</span><span id=__span-2-3><a id=__codelineno-2-3 name=__codelineno-2-3 href=#__codelineno-2-3></a><span class=w> </span><span class=nt>client_id</span><span class=p>:</span><span class=w> </span><span class=s>"headscale"</span>
|
||||
</span><span id=__span-2-4><a id=__codelineno-2-4 name=__codelineno-2-4 href=#__codelineno-2-4></a><span class=w> </span><span class=nt>client_secret</span><span class=p>:</span><span class=w> </span><span class=s>"generated-secret"</span>
|
||||
</span><span id=__span-2-5><a id=__codelineno-2-5 name=__codelineno-2-5 href=#__codelineno-2-5></a><span class=hll><span class=w> </span><span class=nt>allowed_domains</span><span class=p>:</span>
|
||||
</span></span><span id=__span-2-6><a id=__codelineno-2-6 name=__codelineno-2-6 href=#__codelineno-2-6></a><span class=hll><span class=w> </span><span class="p p-Indicator">-</span><span class=w> </span><span class=s>"example.com"</span>
|
||||
</span></span></code></pre></div> </div> <div class=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>A verified email address is required <a href=#control-email-verification>unless email verification is disabled</a>.</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> <div class="language-yaml highlight"><pre><span></span><code><span id=__span-3-1><a id=__codelineno-3-1 name=__codelineno-3-1 href=#__codelineno-3-1></a><span class=nt>oidc</span><span class=p>:</span>
|
||||
</span><span id=__span-3-2><a id=__codelineno-3-2 name=__codelineno-3-2 href=#__codelineno-3-2></a><span class=w> </span><span class=nt>issuer</span><span class=p>:</span><span class=w> </span><span class=s>"https://sso.example.com"</span>
|
||||
</span><span id=__span-3-3><a id=__codelineno-3-3 name=__codelineno-3-3 href=#__codelineno-3-3></a><span class=w> </span><span class=nt>client_id</span><span class=p>:</span><span class=w> </span><span class=s>"headscale"</span>
|
||||
</span><span id=__span-3-4><a id=__codelineno-3-4 name=__codelineno-3-4 href=#__codelineno-3-4></a><span class=w> </span><span class=nt>client_secret</span><span class=p>:</span><span class=w> </span><span class=s>"generated-secret"</span>
|
||||
</span><span id=__span-3-5><a id=__codelineno-3-5 name=__codelineno-3-5 href=#__codelineno-3-5></a><span class=hll><span class=w> </span><span class=nt>allowed_users</span><span class=p>:</span>
|
||||
</span></span><span id=__span-3-6><a id=__codelineno-3-6 name=__codelineno-3-6 href=#__codelineno-3-6></a><span class=hll><span class=w> </span><span class="p p-Indicator">-</span><span class=w> </span><span class=s>"alice@example.com"</span>
|
||||
</span></span><span id=__span-3-7><a id=__codelineno-3-7 name=__codelineno-3-7 href=#__codelineno-3-7></a><span class=hll><span class=w> </span><span class="p p-Indicator">-</span><span class=w> </span><span class=s>"bob@example.net"</span>
|
||||
</span></span></code></pre></div> </div> <div class=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> <div class="language-yaml highlight"><pre><span></span><code><span id=__span-4-1><a id=__codelineno-4-1 name=__codelineno-4-1 href=#__codelineno-4-1></a><span class=nt>oidc</span><span class=p>:</span>
|
||||
</span><span id=__span-4-2><a id=__codelineno-4-2 name=__codelineno-4-2 href=#__codelineno-4-2></a><span class=w> </span><span class=nt>issuer</span><span class=p>:</span><span class=w> </span><span class=s>"https://sso.example.com"</span>
|
||||
</span><span id=__span-4-3><a id=__codelineno-4-3 name=__codelineno-4-3 href=#__codelineno-4-3></a><span class=w> </span><span class=nt>client_id</span><span class=p>:</span><span class=w> </span><span class=s>"headscale"</span>
|
||||
</span><span id=__span-4-4><a id=__codelineno-4-4 name=__codelineno-4-4 href=#__codelineno-4-4></a><span class=w> </span><span class=nt>client_secret</span><span class=p>:</span><span class=w> </span><span class=s>"generated-secret"</span>
|
||||
</span><span id=__span-4-5><a id=__codelineno-4-5 name=__codelineno-4-5 href=#__codelineno-4-5></a><span class=hll><span class=w> </span><span class=nt>scope</span><span class=p>:</span><span class=w> </span><span class="p p-Indicator">[</span><span class=s>"openid"</span><span class="p p-Indicator">,</span><span class=w> </span><span class=s>"profile"</span><span class="p p-Indicator">,</span><span class=w> </span><span class=s>"email"</span><span class="p p-Indicator">,</span><span class=w> </span><span class=s>"groups"</span><span class="p p-Indicator">]</span>
|
||||
</span></span><span id=__span-4-6><a id=__codelineno-4-6 name=__codelineno-4-6 href=#__codelineno-4-6></a><span class=hll><span class=w> </span><span class=nt>allowed_groups</span><span class=p>:</span>
|
||||
</span></span><span id=__span-4-7><a id=__codelineno-4-7 name=__codelineno-4-7 href=#__codelineno-4-7></a><span class=hll><span class=w> </span><span class="p p-Indicator">-</span><span class=w> </span><span class=s>"headscale_users"</span>
|
||||
</span></span></code></pre></div> </div> </div> </div> <h3 id=control-email-verification>Control email verification<a class=headerlink href=#control-email-verification title="Permanent link">¶</a></h3> <p>Headscale uses the <code>email</code> claim from the identity provider to synchronize the email address to its user profile. By default, a user's email address is only synchronized when the identity provider reports the email address as verified via the <code>email_verified: true</code> claim.</p> <p>Unverified emails may be allowed in case an identity provider does not send the <code>email_verified</code> claim or email verification is not required. In that case, a user's email address is always synchronized to the user profile.</p> <div class="language-yaml highlight"><pre><span></span><code><span id=__span-5-1><a id=__codelineno-5-1 name=__codelineno-5-1 href=#__codelineno-5-1></a><span class=nt>oidc</span><span class=p>:</span>
|
||||
</span><span id=__span-5-2><a id=__codelineno-5-2 name=__codelineno-5-2 href=#__codelineno-5-2></a><span class=w> </span><span class=nt>issuer</span><span class=p>:</span><span class=w> </span><span class=s>"https://sso.example.com"</span>
|
||||
</span><span id=__span-5-3><a id=__codelineno-5-3 name=__codelineno-5-3 href=#__codelineno-5-3></a><span class=w> </span><span class=nt>client_id</span><span class=p>:</span><span class=w> </span><span class=s>"headscale"</span>
|
||||
</span><span id=__span-5-4><a id=__codelineno-5-4 name=__codelineno-5-4 href=#__codelineno-5-4></a><span class=w> </span><span class=nt>client_secret</span><span class=p>:</span><span class=w> </span><span class=s>"generated-secret"</span>
|
||||
</span><span id=__span-5-5><a id=__codelineno-5-5 name=__codelineno-5-5 href=#__codelineno-5-5></a><span class=hll><span class=w> </span><span class=nt>email_verified_required</span><span class=p>:</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">false</span>
|
||||
</span></span></code></pre></div> <h3 id=customize-node-expiration>Customize node expiration<a class=headerlink href=#customize-node-expiration title="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 can be configured via the top-level <code>node.expiry</code> setting.</p> <div class="tabbed-set tabbed-alternate" data-tabs=4:2><input checked=checked id=__tabbed_4_1 name=__tabbed_4 type=radio><input id=__tabbed_4_2 name=__tabbed_4 type=radio><div class=tabbed-labels><label for=__tabbed_4_1>Customize node expiration</label><label for=__tabbed_4_2>Use expiration from Access Token</label></div> <div class=tabbed-content> <div class=tabbed-block> <div class="language-yaml highlight"><pre><span></span><code><span id=__span-6-1><a id=__codelineno-6-1 name=__codelineno-6-1 href=#__codelineno-6-1></a><span class=nt>node</span><span class=p>:</span>
|
||||
</span><span id=__span-6-2><a id=__codelineno-6-2 name=__codelineno-6-2 href=#__codelineno-6-2></a><span class=hll><span class=w> </span><span class=nt>expiry</span><span class=p>:</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">30d</span><span class=w> </span><span class=c1># Use 0 to disable node expiration</span>
|
||||
</span></span></code></pre></div> </div> <div class=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> <div class="language-yaml highlight"><pre><span></span><code><span id=__span-7-1><a id=__codelineno-7-1 name=__codelineno-7-1 href=#__codelineno-7-1></a><span class=nt>oidc</span><span class=p>:</span>
|
||||
</span><span id=__span-7-2><a id=__codelineno-7-2 name=__codelineno-7-2 href=#__codelineno-7-2></a><span class=w> </span><span class=nt>issuer</span><span class=p>:</span><span class=w> </span><span class=s>"https://sso.example.com"</span>
|
||||
</span><span id=__span-7-3><a id=__codelineno-7-3 name=__codelineno-7-3 href=#__codelineno-7-3></a><span class=w> </span><span class=nt>client_id</span><span class=p>:</span><span class=w> </span><span class=s>"headscale"</span>
|
||||
</span><span id=__span-7-4><a id=__codelineno-7-4 name=__codelineno-7-4 href=#__codelineno-7-4></a><span class=w> </span><span class=nt>client_secret</span><span class=p>:</span><span class=w> </span><span class=s>"generated-secret"</span>
|
||||
</span><span id=__span-7-5><a id=__codelineno-7-5 name=__codelineno-7-5 href=#__codelineno-7-5></a><span class=hll><span class=w> </span><span class=nt>use_expiry_from_token</span><span class=p>:</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">true</span>
|
||||
</span></span></code></pre></div> </div> </div> </div> <div class="admonition tip"> <p class=admonition-title>Expire a node and force re-authentication</p> <p>A node can be expired immediately via:</p> <div class="language-console highlight"><pre><span></span><code><span id=__span-8-1><a id=__codelineno-8-1 name=__codelineno-8-1 href=#__codelineno-8-1></a><span class=go>headscale node expire -i <NODE_ID></span>
|
||||
</span></code></pre></div> </div> <h3 id=reference-a-user-in-the-policy>Reference a user in the policy<a class=headerlink href=#reference-a-user-in-the-policy title="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 (this value is currently only available from the <a href=../api/ >API</a>, database or directly from your identity provider)</li> </ul> <div class="admonition note"> <p class=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 Headscale username <code>ssmith</code> has to be written as <code>ssmith@</code> to be correctly identified as user within the policy.</p> <p>Ensure that the Headscale username itself does not end with <code>@</code>.</p> </div> <div class="admonition warning"> <p class=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> <div class="admonition tip"> <p class=admonition-title>Howto use the provider identifier in the policy</p> <p>The provider identifier uniquely identifies an OIDC user and a well-behaving identity provider guarantees that this value never changes for a particular user. It is usually an opaque and long string and its value is currently only available from the <a href=../api/ >API</a>, database or directly from your identity provider).</p> <p>Use the <a href=../api/ >API</a> with the <code>/api/v1/user</code> endpoint to fetch the provider identifier (<code>providerId</code>). The value (be sure to append an <code>@</code> in case the provider identifier doesn't already contain an <code>@</code> somewhere) can be used directly to reference a user in the policy. To improve readability of the policy, one may use the <code>groups</code> section as an alias:</p> <div class="language-json highlight"><pre><span></span><code><span id=__span-9-1><a id=__codelineno-9-1 name=__codelineno-9-1 href=#__codelineno-9-1></a><span class=p>{</span>
|
||||
</span><span id=__span-9-2><a id=__codelineno-9-2 name=__codelineno-9-2 href=#__codelineno-9-2></a><span class=w> </span><span class=nt>"groups"</span><span class=p>:</span><span class=w> </span><span class=p>{</span>
|
||||
</span><span id=__span-9-3><a id=__codelineno-9-3 name=__codelineno-9-3 href=#__codelineno-9-3></a><span class=w> </span><span class=nt>"group:alice"</span><span class=p>:</span><span class=w> </span><span class=p>[</span>
|
||||
</span><span id=__span-9-4><a id=__codelineno-9-4 name=__codelineno-9-4 href=#__codelineno-9-4></a><span class=w> </span><span class=s2>"https://sso.example.com/oauth2/openid/59ac9125-c31b-46c5-814e-06242908cf57@"</span>
|
||||
</span><span id=__span-9-5><a id=__codelineno-9-5 name=__codelineno-9-5 href=#__codelineno-9-5></a><span class=w> </span><span class=p>]</span>
|
||||
</span><span id=__span-9-6><a id=__codelineno-9-6 name=__codelineno-9-6 href=#__codelineno-9-6></a><span class=w> </span><span class=p>},</span>
|
||||
</span><span id=__span-9-7><a id=__codelineno-9-7 name=__codelineno-9-7 href=#__codelineno-9-7></a><span class=w> </span><span class=nt>"grants"</span><span class=p>:</span><span class=w> </span><span class=p>[</span>
|
||||
</span><span id=__span-9-8><a id=__codelineno-9-8 name=__codelineno-9-8 href=#__codelineno-9-8></a><span class=w> </span><span class=p>{</span>
|
||||
</span><span id=__span-9-9><a id=__codelineno-9-9 name=__codelineno-9-9 href=#__codelineno-9-9></a><span class=w> </span><span class=nt>"src"</span><span class=p>:</span><span class=w> </span><span class=p>[</span><span class=s2>"group:alice"</span><span class=p>],</span>
|
||||
</span><span id=__span-9-10><a id=__codelineno-9-10 name=__codelineno-9-10 href=#__codelineno-9-10></a><span class=w> </span><span class=nt>"dst"</span><span class=p>:</span><span class=w> </span><span class=p>[</span><span class=s2>"*"</span><span class=p>],</span>
|
||||
</span><span id=__span-9-11><a id=__codelineno-9-11 name=__codelineno-9-11 href=#__codelineno-9-11></a><span class=w> </span><span class=nt>"ip"</span><span class=p>:</span><span class=w> </span><span class=p>[</span><span class=s2>"*"</span><span class=p>]</span>
|
||||
</span><span id=__span-9-12><a id=__codelineno-9-12 name=__codelineno-9-12 href=#__codelineno-9-12></a><span class=w> </span><span class=p>}</span>
|
||||
</span><span id=__span-9-13><a id=__codelineno-9-13 name=__codelineno-9-13 href=#__codelineno-9-13></a><span class=w> </span><span class=p>]</span>
|
||||
</span><span id=__span-9-14><a id=__codelineno-9-14 name=__codelineno-9-14 href=#__codelineno-9-14></a><span class=p>}</span>
|
||||
</span></code></pre></div> </div> <h2 id=supported-oidc-claims>Supported OIDC claims<a class=headerlink href=#supported-oidc-claims title="Permanent link">¶</a></h2> <p>Headscale uses <a href=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 and 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 verified emails are synchronized, unless <code>email_verified_required: false</code> is configured</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><a href=#authorize-users-with-filters>Only used to filter for allowed groups</a></td> </tr> </tbody> </table> <h2 id=limitations>Limitations<a class=headerlink href=#limitations title="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 policy rules.</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> </ul> <p>Please see the <a href=https://github.com/juanfont/headscale/labels/OIDC>GitHub label "OIDC"</a> for OIDC related issues.</p> <h2 id=identity-provider-specific-configuration>Identity provider specific configuration<a class=headerlink href=#identity-provider-specific-configuration title="Permanent link">¶</a></h2> <div class="admonition warning"> <p class=admonition-title>Third-party software and services</p> <p>This section of the documentation is specific for third-party software and services. We recommend users read the third-party documentation on how to configure and integrate an OIDC client. Please see the <a href=#configuration>Configuration section</a> for a description of Headscale's OIDC related configuration settings.</p> </div> <p>Any identity provider with OpenID Connect support should "just work" with Headscale. The following identity providers are known to work:</p> <ul> <li><a href=#authelia>Authelia</a></li> <li><a href=#authentik>Authentik</a></li> <li><a href=#kanidm>Kanidm</a></li> <li><a href=#keycloak>Keycloak</a></li> </ul> <h3 id=authelia>Authelia<a class=headerlink href=#authelia title="Permanent link">¶</a></h3> <p>Authelia is fully supported by Headscale.</p> <h3 id=authentik>Authentik<a class=headerlink href=#authentik title="Permanent link">¶</a></h3> <ul> <li>Authentik is fully supported by Headscale.</li> <li><a href=https://github.com/juanfont/headscale/issues/2446>Headscale does not support JSON Web Encryption</a>. Leave the field <code>Encryption Key</code> in the providers section unset.</li> <li>See Authentik's <a href=https://integrations.goauthentik.io/networking/headscale/ >Integrate with Headscale</a></li> </ul> <h3 id=google-oauth>Google OAuth<a class=headerlink href=#google-oauth title="Permanent link">¶</a></h3> <div class="admonition warning"> <p class=admonition-title>No username due to missing preferred_username claim</p> <p>Google OAuth does not send the <code>preferred_username</code> claim when the <code>profile</code> scope is requested. The username in Headscale will be blank/not set.</p> </div> <p>In order to integrate Headscale with Google, you'll need to have a <a href=https://console.cloud.google.com>Google Cloud Console</a> account.</p> <p>Google OAuth has a <a href="https://support.google.com/cloud/answer/9110914?hl=en">verification process</a> if you need to have users authenticate who are outside of your domain. If you only need to authenticate users from your domain name (ie <code>@example.com</code>), you don't need to go through the verification process.</p> <p>However if you don't have a domain, or need to add users outside of your domain, you can manually add emails via Google Console.</p> <h4 id=steps>Steps<a class=headerlink href=#steps title="Permanent link">¶</a></h4> <ol> <li>Go to <a href=https://console.cLine truncated
|
||||
</span></code></pre></div> Once configured, the short username in Headscale will be <code>alice</code> and can be referred to as <code>alice@</code> in the policy.</li> </ul> <h3 id=keycloak>Keycloak<a class=headerlink href=#keycloak title="Permanent link">¶</a></h3> <p>Keycloak is fully supported by Headscale.</p> <h4 id=additional-configuration-to-use-the-allowed-groups-filter>Additional configuration to use the allowed groups filter<a class=headerlink href=#additional-configuration-to-use-the-allowed-groups-filter title="Permanent link">¶</a></h4> <p>Keycloak has no built-in client scope for the OIDC <code>groups</code> claim. This extra configuration step is <strong>only</strong> needed if you need to <a href=#authorize-users-with-filters>authorize access based on group membership</a>.</p> <ul> <li>Create a new client scope <code>groups</code> for OpenID Connect:<ul> <li>Configure a <code>Group Membership</code> mapper with name <code>groups</code> and the token claim name <code>groups</code>.</li> <li>Add the mapper to at least the UserInfo endpoint.</li> </ul> </li> <li>Configure the new client scope for your Headscale client:<ul> <li>Edit the Headscale client.</li> <li>Search for the client scope <code>group</code>.</li> <li>Add it with assigned type <code>Default</code>.</li> </ul> </li> <li><a href=#authorize-users-with-filters>Configure the allowed groups in Headscale</a>. How groups need to be specified depends on Keycloak's <code>Full group path</code> option:<ul> <li><code>Full group path</code> is enabled: groups contain their full path, e.g. <code>/top/group1</code></li> <li><code>Full group path</code> is disabled: only the name of the group is used, e.g. <code>group1</code></li> </ul> </li> </ul> <h3 id=microsoft-entra-id>Microsoft Entra ID<a class=headerlink href=#microsoft-entra-id title="Permanent link">¶</a></h3> <p>In order to integrate Headscale with Microsoft Entra ID, you'll need to provision an App Registration with the correct scopes and redirect URI.</p> <p><a href=#basic-configuration>Configure Headscale following the "Basic configuration" steps</a>. The issuer URL for Microsoft Entra ID is: <code>https://login.microsoftonline.com/<tenant-UUID>/v2.0</code>. The following <code>extra_params</code> might be useful:</p> <ul> <li><code>domain_hint: example.com</code> to use your own domain</li> <li><code>prompt: select_account</code> to force an account picker during login</li> </ul> <p>When using Microsoft Entra ID together with the <a href=#authorize-users-with-filters>allowed groups filter</a>, configure the Headscale OIDC scope without the <code>groups</code> claim, for example:</p> <div class="language-yaml highlight"><pre><span></span><code><span id=__span-11-1><a id=__codelineno-11-1 name=__codelineno-11-1 href=#__codelineno-11-1></a><span class=nt>oidc</span><span class=p>:</span>
|
||||
</span><span id=__span-11-2><a id=__codelineno-11-2 name=__codelineno-11-2 href=#__codelineno-11-2></a><span class=w> </span><span class=nt>scope</span><span class=p>:</span><span class=w> </span><span class="p p-Indicator">[</span><span class=s>"openid"</span><span class="p p-Indicator">,</span><span class=w> </span><span class=s>"profile"</span><span class="p p-Indicator">,</span><span class=w> </span><span class=s>"email"</span><span class="p p-Indicator">]</span>
|
||||
</span></code></pre></div> <p>Groups for the <a href=#authorize-users-with-filters>allowed groups filter</a> need to be specified with their group ID(UUID) instead of the group name.</p> <h2 id=switching-oidc-providers>Switching OIDC providers<a class=headerlink href=#switching-oidc-providers title="Permanent link">¶</a></h2> <p>Headscale only supports a single OIDC provider in its configuration, but it does store the provider identifier of each user. When switching providers, this might lead to issues with existing users: all user details (name, email, groups) might be identical with the new provider, but the identifier will differ. Headscale will be unable to create a new user as the name and email will already be in use for the existing users.</p> <p>At this time, you will need to manually update the <code>provider_identifier</code> column in the <code>users</code> table for each user with the appropriate value for the new provider. The identifier is built from the <code>iss</code> and <code>sub</code> claims of the OIDC ID token, for example <code>https://id.example.com/12340987</code>.</p> </article> </div> <script>var target=document.getElementById(location.hash.slice(1));target&&target.name&&(target.checked=target.name.startsWith("__tabbed_"))</script> </div> <div class=md-top data-md-component=top hidden> <div class=md-top__center> <button type=button class="md-top__button md-top__button--main" data-md-action=top> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M13 20h-2V8l-5.5 5.5-1.42-1.42L12 4.16l7.92 7.92-1.42 1.42L13 8z"/></svg> <span>Back to top</span> </button> <label class="md-top__button md-top__side md-top__side--nav" for=__drawer> <svg xmlns=http://www.w3.org/2000/svg fill=none stroke=currentColor stroke-linecap=round stroke-linejoin=round stroke-width=2 class="lucide lucide-panel-left" viewbox="0 0 24 24"><rect width=18 height=18 x=3 y=3 rx=2 /><path d="M9 3v18"/></svg> </label> <label class="md-top__button md-top__side md-top__side--toc" for=__toc> <svg xmlns=http://www.w3.org/2000/svg fill=none stroke=currentColor stroke-linecap=round stroke-linejoin=round stroke-width=2 class="lucide lucide-panel-right" viewbox="0 0 24 24"><rect width=18 height=18 x=3 y=3 rx=2 /><path d="M15 3v18"/></svg> </label> </div> </div> </main> <footer class=md-footer> <nav class="md-footer__inner md-grid" aria-label=Footer> <a href=../registration/ class="md-footer__link md-footer__link--prev" aria-label="Previous: Registration methods"> <div class="md-footer__button md-icon"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M20 11v2H8l5.5 5.5-1.42 1.42L4.16 12l7.92-7.92L13.5 5.5 8 11z"/></svg> </div> <div class=md-footer__title> <span class=md-footer__direction> Previous </span> <div class=md-ellipsis> Registration methods </div> </div> </a> <a href=../routes/ class="md-footer__link md-footer__link--next" aria-label="Next: Routes"> <div class=md-footer__title> <span class=md-footer__direction> Next </span> <div class=md-ellipsis> Routes </div> </div> <div class="md-footer__button md-icon"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M4 11v2h12l-5.5 5.5 1.42 1.42L19.84 12l-7.92-7.92L10.5 5.5 16 11z"/></svg> </div> </a> </nav> <div class="md-footer-meta md-typeset"> <div class="md-footer-meta__inner md-grid"> <div class=md-copyright> <div class=md-copyright__highlight> Copyright © 2026 Headscale authors </div> Made with <a href=https://jaywhj.github.io/mkdocs-materialx/ target=_blank rel=noopener> MaterialX </a> </div> <div class=md-social> <a href=https://github.com/juanfont/headscale target=_blank rel=noopener title=github.com class=md-social__link> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 512 512"><!-- Font Awesome Free 7.1.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2025 Fonticons, Inc.--><path d="M173.9 397.4c0 2-2.3 3.6-5.2 3.6-3.3.3-5.6-1.3-5.6-3.6 0-2 2.3-3.6 5.2-3.6 3-.3 5.6 1.3 5.6 3.6m-31.1-4.5c-.7 2 1.3 4.3 4.3 4.9 2.6 1 5.6 0 6.2-2s-1.3-4.3-4.3-5.2c-2.6-.7-5.5.3-6.2 2.3m44.2-1.7c-2.9.7-4.9 2.6-4.6 4.9.3 2 2.9 3.3 5.9 2.6 2.9-.7 4.9-2.6 4.6-4.6-.3-1.9-3-3.2-5.9-2.9M252.8 8C114.1 8 8 113.3 8 252c0 110.9 69.8 205.8 169.5 239.2 12.8 2.3 17.3-5.6 17.3-12.1 0-6.2-.3-40.4-.3-61.4 0 0-70 15-84.7-29.8 0 0-11.4-29.1-27.8-36.6 0 0-22.9-15.7 1.6-15.4 0 0 24.9 2 38.6 25.8 21.9 38.6 58.6 27.5 72.9 20.9 2.3-16 8.8-27.1 16-33.7-55.9-6.2-112.3-14.3-112.3-110.5 0-27.5 7.6-41.3 23.6-58.9-2.6-6.5-11.1-33.3 2.6-67.9 20.9-6.5 69 27 69 27 20-5.6 41.5-8.5 62.8-8.5s42.8 2.9 62.8 8.5c0 0 48.1-33.6 69-27 13.7 34.7 5.2 61.4 2.6 67.9 16 17.7 25.8 31.5 25.8 58.9 0 96.5-58.9 104.2-114.8 110.5 9.2 7.9 17 22.9 17 46.4 0 33.7-.3 75.4-.3 83.6 0 6.5 4.6 14.4 17.3 12.1C436.2 457.8 504 362.9 504 252 504 113.3 391.5 8 252.8 8M105.2 352.9c-1.3 1-1 3.3.7 5.2 1.6 1.6 3.9 2.3 5.2 1 1.3-1 1-3.3-.7-5.2-1.6-1.6-3.9-2.3-5.2-1m-10.8-8.1c-.7 1.3.3 2.9 2Line truncated
|
||||
Reference in new issue
Block a user