Deployed d461db3a to development with MkDocs 1.6.1 and mike 2.1.3

This commit is contained in:
github-actions committed 2025-07-04 12:47:06 +00:00
1 parent 2558edbdf4
commit 2c5eb96f5f
35 files changed
+117 -234

No files matched your search

+42 -159
View File
@@ -1,159 +1,42 @@
<!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/development/ref/oidc/ rel=canonical><link href=../configuration/ rel=prev><link href=../routes/ rel=next><link rel=icon href=../../assets/favicon.png><meta name=generator content="mkdocs-1.6.1, mkdocs-material-9.6.14"><title>OIDC authentication - Headscale</title><link rel=stylesheet href=../../assets/stylesheets/main.342714a4.min.css><link rel=stylesheet href=../../assets/stylesheets/palette.06af60db.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="OIDC authentication - 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/development/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/development/ref/oidc/ property=og:url><meta name=twitter:card content=summary_large_image><meta name=twitter:title content="OIDC authentication - Headscale"><meta name=twitter:description content="An open source, self-hosted implementation of the Tailscale control server."><meta name=twitter:image content=https://juanfont.github.io/headscale/development/assets/images/social/ref/oidc.png></head> <body dir=ltr data-md-color-scheme=default data-md-color-primary=white data-md-color-accent=indigo> <input class=md-toggle data-md-toggle=drawer type=checkbox id=__drawer autocomplete=off> <input class=md-toggle data-md-toggle=search type=checkbox id=__search autocomplete=off> <label class=md-overlay for=__drawer></label> <div data-md-component=skip> <a href=#configuring-headscale-to-use-oidc-authentication 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=../../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> OIDC authentication </span> </div> </div> </div> <form class=md-header__option data-md-component=palette> <input class=md-option data-md-color-media data-md-color-scheme=default data-md-color-primary=white data-md-color-accent=indigo aria-label="Switch to dark mode" type=radio name=__palette id=__palette_0> <label class="md-header__button md-icon" title="Switch to dark mode" for=__palette_1 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 data-md-color-scheme=slate data-md-color-primary=indigo data-md-color-accent=indigo aria-label="Switch to light mode" type=radio name=__palette id=__palette_1> <label class="md-header__button md-icon" title="Switch to light mode" for=__palette_0 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 18c-.89 0-1.74-.2-2.5-.55C11.56 16.5 13 14.42 13 12s-1.44-4.5-3.5-5.45C10.26 6.2 11.11 6 12 6a6 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> </form> <script>var palette=__md_get("__palette");if(palette&&palette.color){if("(prefers-color-scheme)"===palette.color.media){var media=matchMedia("(prLine 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=c1># Block further startup until the OIDC provider is healthy and available</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>only_start_if_oidc_is_available</span><span class=p>:</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">true</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=c1># Specified by your OIDC provider</span>
</span><span id=__span-0-5><a id=__codelineno-0-5 name=__codelineno-0-5 href=#__codelineno-0-5></a><span class=w> </span><span class=nt>issuer</span><span class=p>:</span><span class=w> </span><span class=s>&quot;https://your-oidc.issuer.com/path&quot;</span>
</span><span id=__span-0-6><a id=__codelineno-0-6 name=__codelineno-0-6 href=#__codelineno-0-6></a><span class=w> </span><span class=c1># Specified/generated by your OIDC provider</span>
</span><span id=__span-0-7><a id=__codelineno-0-7 name=__codelineno-0-7 href=#__codelineno-0-7></a><span class=w> </span><span class=nt>client_id</span><span class=p>:</span><span class=w> </span><span class=s>&quot;your-oidc-client-id&quot;</span>
</span><span id=__span-0-8><a id=__codelineno-0-8 name=__codelineno-0-8 href=#__codelineno-0-8></a><span class=w> </span><span class=nt>client_secret</span><span class=p>:</span><span class=w> </span><span class=s>&quot;your-oidc-client-secret&quot;</span>
</span><span id=__span-0-9><a id=__codelineno-0-9 name=__codelineno-0-9 href=#__codelineno-0-9></a><span class=w> </span><span class=c1># alternatively, set `client_secret_path` to read the secret from the file.</span>
</span><span id=__span-0-10><a id=__codelineno-0-10 name=__codelineno-0-10 href=#__codelineno-0-10></a><span class=w> </span><span class=c1># It resolves environment variables, making integration to systemd&#39;s</span>
</span><span id=__span-0-11><a id=__codelineno-0-11 name=__codelineno-0-11 href=#__codelineno-0-11></a><span class=w> </span><span class=c1># `LoadCredential` straightforward:</span>
</span><span id=__span-0-12><a id=__codelineno-0-12 name=__codelineno-0-12 href=#__codelineno-0-12></a><span class=w> </span><span class=c1>#client_secret_path: &quot;${CREDENTIALS_DIRECTORY}/oidc_client_secret&quot;</span>
</span><span id=__span-0-13><a id=__codelineno-0-13 name=__codelineno-0-13 href=#__codelineno-0-13></a><span class=w> </span><span class=c1># as third option, it&#39;s also possible to load the oidc secret from environment variables</span>
</span><span id=__span-0-14><a id=__codelineno-0-14 name=__codelineno-0-14 href=#__codelineno-0-14></a><span class=w> </span><span class=c1># set HEADSCALE_OIDC_CLIENT_SECRET to the required value</span>
</span><span id=__span-0-15><a id=__codelineno-0-15 name=__codelineno-0-15 href=#__codelineno-0-15></a>
</span><span id=__span-0-16><a id=__codelineno-0-16 name=__codelineno-0-16 href=#__codelineno-0-16></a><span class=w> </span><span class=c1># Customize the scopes used in the OIDC flow, defaults to &quot;openid&quot;, &quot;profile&quot; and &quot;email&quot; and add custom query</span>
</span><span id=__span-0-17><a id=__codelineno-0-17 name=__codelineno-0-17 href=#__codelineno-0-17></a><span class=w> </span><span class=c1># parameters to the Authorize Endpoint request. Scopes default to &quot;openid&quot;, &quot;profile&quot; and &quot;email&quot;.</span>
</span><span id=__span-0-18><a id=__codelineno-0-18 name=__codelineno-0-18 href=#__codelineno-0-18></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>&quot;openid&quot;</span><span class="p p-Indicator">,</span><span class=w> </span><span class=s>&quot;profile&quot;</span><span class="p p-Indicator">,</span><span class=w> </span><span class=s>&quot;email&quot;</span><span class="p p-Indicator">,</span><span class=w> </span><span class=s>&quot;custom&quot;</span><span class="p p-Indicator">]</span>
</span><span id=__span-0-19><a id=__codelineno-0-19 name=__codelineno-0-19 href=#__codelineno-0-19></a><span class=w> </span><span class=c1># Optional: Passed on to the browser login request – used to tweak behaviour for the OIDC provider</span>
</span><span id=__span-0-20><a id=__codelineno-0-20 name=__codelineno-0-20 href=#__codelineno-0-20></a><span class=w> </span><span class=nt>extra_params</span><span class=p>:</span>
</span><span id=__span-0-21><a id=__codelineno-0-21 name=__codelineno-0-21 href=#__codelineno-0-21></a><span class=w> </span><span class=nt>domain_hint</span><span class=p>:</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">example.com</span>
</span><span id=__span-0-22><a id=__codelineno-0-22 name=__codelineno-0-22 href=#__codelineno-0-22></a>
</span><span id=__span-0-23><a id=__codelineno-0-23 name=__codelineno-0-23 href=#__codelineno-0-23></a><span class=w> </span><span class=c1># Optional: List allowed principal domains and/or users. If an authenticated user&#39;s domain is not in this list,</span>
</span><span id=__span-0-24><a id=__codelineno-0-24 name=__codelineno-0-24 href=#__codelineno-0-24></a><span class=w> </span><span class=c1># the authentication request will be rejected.</span>
</span><span id=__span-0-25><a id=__codelineno-0-25 name=__codelineno-0-25 href=#__codelineno-0-25></a><span class=w> </span><span class=nt>allowed_domains</span><span class=p>:</span>
</span><span id=__span-0-26><a id=__codelineno-0-26 name=__codelineno-0-26 href=#__codelineno-0-26></a><span class=w> </span><span class="p p-Indicator">-</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">example.com</span>
</span><span id=__span-0-27><a id=__codelineno-0-27 name=__codelineno-0-27 href=#__codelineno-0-27></a><span class=w> </span><span class=c1># Optional. Note that groups from Keycloak have a leading &#39;/&#39;.</span>
</span><span id=__span-0-28><a id=__codelineno-0-28 name=__codelineno-0-28 href=#__codelineno-0-28></a><span class=w> </span><span class=nt>allowed_groups</span><span class=p>:</span>
</span><span id=__span-0-29><a id=__codelineno-0-29 name=__codelineno-0-29 href=#__codelineno-0-29></a><span class=w> </span><span class="p p-Indicator">-</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">/headscale</span>
</span><span id=__span-0-30><a id=__codelineno-0-30 name=__codelineno-0-30 href=#__codelineno-0-30></a><span class=w> </span><span class=c1># Optional.</span>
</span><span id=__span-0-31><a id=__codelineno-0-31 name=__codelineno-0-31 href=#__codelineno-0-31></a><span class=w> </span><span class=nt>allowed_users</span><span class=p>:</span>
</span><span id=__span-0-32><a id=__codelineno-0-32 name=__codelineno-0-32 href=#__codelineno-0-32></a><span class=w> </span><span class="p p-Indicator">-</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">alice@example.com</span>
</span><span id=__span-0-33><a id=__codelineno-0-33 name=__codelineno-0-33 href=#__codelineno-0-33></a>
</span><span id=__span-0-34><a id=__codelineno-0-34 name=__codelineno-0-34 href=#__codelineno-0-34></a><span class=w> </span><span class=c1># Optional: PKCE (Proof Key for Code Exchange) configuration</span>
</span><span id=__span-0-35><a id=__codelineno-0-35 name=__codelineno-0-35 href=#__codelineno-0-35></a><span class=w> </span><span class=c1># PKCE adds an additional layer of security to the OAuth 2.0 authorization code flow</span>
</span><span id=__span-0-36><a id=__codelineno-0-36 name=__codelineno-0-36 href=#__codelineno-0-36></a><span class=w> </span><span class=c1># by preventing authorization code interception attacks</span>
</span><span id=__span-0-37><a id=__codelineno-0-37 name=__codelineno-0-37 href=#__codelineno-0-37></a><span class=w> </span><span class=c1># See https://datatracker.ietf.org/doc/html/rfc7636</span>
</span><span id=__span-0-38><a id=__codelineno-0-38 name=__codelineno-0-38 href=#__codelineno-0-38></a><span class=w> </span><span class=nt>pkce</span><span class=p>:</span>
</span><span id=__span-0-39><a id=__codelineno-0-39 name=__codelineno-0-39 href=#__codelineno-0-39></a><span class=w> </span><span class=c1># Enable or disable PKCE support (default: false)</span>
</span><span id=__span-0-40><a id=__codelineno-0-40 name=__codelineno-0-40 href=#__codelineno-0-40></a><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">false</span>
</span><span id=__span-0-41><a id=__codelineno-0-41 name=__codelineno-0-41 href=#__codelineno-0-41></a><span class=w> </span><span class=c1># PKCE method to use:</span>
</span><span id=__span-0-42><a id=__codelineno-0-42 name=__codelineno-0-42 href=#__codelineno-0-42></a><span class=w> </span><span class=c1># - plain: Use plain code verifier</span>
</span><span id=__span-0-43><a id=__codelineno-0-43 name=__codelineno-0-43 href=#__codelineno-0-43></a><span class=w> </span><span class=c1># - S256: Use SHA256 hashed code verifier (default, recommended)</span>
</span><span id=__span-0-44><a id=__codelineno-0-44 name=__codelineno-0-44 href=#__codelineno-0-44></a><span class=w> </span><span class=nt>method</span><span class=p>:</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">S256</span>
</span></code></pre></div> <h2 id=azure-ad-example>Azure AD example<a class=headerlink href=#azure-ad-example title="Permanent link">&para;</a></h2> <p>In order to integrate headscale with Azure Active Directory, we'll need to provision an App Registration with the correct scopes and redirect URI. Here with Terraform:</p> <div class="language-hcl highlight"><span class=filename>terraform.hcl</span><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=kr>resource</span><span class=w> </span><span class=nc>&quot;azuread_application&quot;</span><span class=w> </span><span class=nv>&quot;headscale&quot;</span><span class=w> </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=na>display_name</span><span class=w> </span><span class=o>=</span><span class=w> </span><span class=s2>&quot;Headscale&quot;</span>
</span><span id=__span-1-3><a id=__codelineno-1-3 name=__codelineno-1-3 href=#__codelineno-1-3></a>
</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=na>sign_in_audience</span><span class=w> </span><span class=o>=</span><span class=w> </span><span class=s2>&quot;AzureADMyOrg&quot;</span>
</span><span id=__span-1-5><a id=__codelineno-1-5 name=__codelineno-1-5 href=#__codelineno-1-5></a><span class=w> </span><span class=na>fallback_public_client_enabled</span><span class=w> </span><span class=o>=</span><span class=w> </span><span class=no>false</span>
</span><span id=__span-1-6><a id=__codelineno-1-6 name=__codelineno-1-6 href=#__codelineno-1-6></a>
</span><span id=__span-1-7><a id=__codelineno-1-7 name=__codelineno-1-7 href=#__codelineno-1-7></a><span class=w> </span><span class=nb>required_resource_access</span><span class=w> </span><span class=p>{</span>
</span><span id=__span-1-8><a id=__codelineno-1-8 name=__codelineno-1-8 href=#__codelineno-1-8></a><span class=c1> // Microsoft Graph</span>
</span><span id=__span-1-9><a id=__codelineno-1-9 name=__codelineno-1-9 href=#__codelineno-1-9></a><span class=w> </span><span class=na>resource_app_id</span><span class=w> </span><span class=o>=</span><span class=w> </span><span class=s2>&quot;00000003-0000-0000-c000-000000000000&quot;</span>
</span><span id=__span-1-10><a id=__codelineno-1-10 name=__codelineno-1-10 href=#__codelineno-1-10></a>
</span><span id=__span-1-11><a id=__codelineno-1-11 name=__codelineno-1-11 href=#__codelineno-1-11></a><span class=w> </span><span class=nb>resource_access</span><span class=w> </span><span class=p>{</span>
</span><span id=__span-1-12><a id=__codelineno-1-12 name=__codelineno-1-12 href=#__codelineno-1-12></a><span class=c1> // scope: profile</span>
</span><span id=__span-1-13><a id=__codelineno-1-13 name=__codelineno-1-13 href=#__codelineno-1-13></a><span class=w> </span><span class=na>id</span><span class=w> </span><span class=o>=</span><span class=w> </span><span class=s2>&quot;14dad69e-099b-42c9-810b-d002981feec1&quot;</span>
</span><span id=__span-1-14><a id=__codelineno-1-14 name=__codelineno-1-14 href=#__codelineno-1-14></a><span class=w> </span><span class=na>type</span><span class=w> </span><span class=o>=</span><span class=w> </span><span class=s2>&quot;Scope&quot;</span>
</span><span id=__span-1-15><a id=__codelineno-1-15 name=__codelineno-1-15 href=#__codelineno-1-15></a><span class=w> </span><span class=p>}</span>
</span><span id=__span-1-16><a id=__codelineno-1-16 name=__codelineno-1-16 href=#__codelineno-1-16></a><span class=w> </span><span class=nb>resource_access</span><span class=w> </span><span class=p>{</span>
</span><span id=__span-1-17><a id=__codelineno-1-17 name=__codelineno-1-17 href=#__codelineno-1-17></a><span class=c1> // scope: openid</span>
</span><span id=__span-1-18><a id=__codelineno-1-18 name=__codelineno-1-18 href=#__codelineno-1-18></a><span class=w> </span><span class=na>id</span><span class=w> </span><span class=o>=</span><span class=w> </span><span class=s2>&quot;37f7f235-527c-4136-accd-4a02d197296e&quot;</span>
</span><span id=__span-1-19><a id=__codelineno-1-19 name=__codelineno-1-19 href=#__codelineno-1-19></a><span class=w> </span><span class=na>type</span><span class=w> </span><span class=o>=</span><span class=w> </span><span class=s2>&quot;Scope&quot;</span>
</span><span id=__span-1-20><a id=__codelineno-1-20 name=__codelineno-1-20 href=#__codelineno-1-20></a><span class=w> </span><span class=p>}</span>
</span><span id=__span-1-21><a id=__codelineno-1-21 name=__codelineno-1-21 href=#__codelineno-1-21></a><span class=w> </span><span class=nb>resource_access</span><span class=w> </span><span class=p>{</span>
</span><span id=__span-1-22><a id=__codelineno-1-22 name=__codelineno-1-22 href=#__codelineno-1-22></a><span class=c1> // scope: email</span>
</span><span id=__span-1-23><a id=__codelineno-1-23 name=__codelineno-1-23 href=#__codelineno-1-23></a><span class=w> </span><span class=na>id</span><span class=w> </span><span class=o>=</span><span class=w> </span><span class=s2>&quot;64a6cdd6-aab1-4aaf-94b8-3cc8405e90d0&quot;</span>
</span><span id=__span-1-24><a id=__codelineno-1-24 name=__codelineno-1-24 href=#__codelineno-1-24></a><span class=w> </span><span class=na>type</span><span class=w> </span><span class=o>=</span><span class=w> </span><span class=s2>&quot;Scope&quot;</span>
</span><span id=__span-1-25><a id=__codelineno-1-25 name=__codelineno-1-25 href=#__codelineno-1-25></a><span class=w> </span><span class=p>}</span>
</span><span id=__span-1-26><a id=__codelineno-1-26 name=__codelineno-1-26 href=#__codelineno-1-26></a><span class=w> </span><span class=p>}</span>
</span><span id=__span-1-27><a id=__codelineno-1-27 name=__codelineno-1-27 href=#__codelineno-1-27></a><span class=w> </span><span class=nb>web</span><span class=w> </span><span class=p>{</span>
</span><span id=__span-1-28><a id=__codelineno-1-28 name=__codelineno-1-28 href=#__codelineno-1-28></a><span class=c1> # Points at your running headscale instance</span>
</span><span id=__span-1-29><a id=__codelineno-1-29 name=__codelineno-1-29 href=#__codelineno-1-29></a><span class=w> </span><span class=na>redirect_uris</span><span class=w> </span><span class=o>=</span><span class=w> </span><span class=p>[</span><span class=s2>&quot;https://headscale.example.com/oidc/callback&quot;</span><span class=p>]</span>
</span><span id=__span-1-30><a id=__codelineno-1-30 name=__codelineno-1-30 href=#__codelineno-1-30></a>
</span><span id=__span-1-31><a id=__codelineno-1-31 name=__codelineno-1-31 href=#__codelineno-1-31></a><span class=w> </span><span class=nb>implicit_grant</span><span class=w> </span><span class=p>{</span>
</span><span id=__span-1-32><a id=__codelineno-1-32 name=__codelineno-1-32 href=#__codelineno-1-32></a><span class=w> </span><span class=na>access_token_issuance_enabled</span><span class=w> </span><span class=o>=</span><span class=w> </span><span class=no>false</span>
</span><span id=__span-1-33><a id=__codelineno-1-33 name=__codelineno-1-33 href=#__codelineno-1-33></a><span class=w> </span><span class=na>id_token_issuance_enabled</span><span class=w> </span><span class=o>=</span><span class=w> </span><span class=no>true</span>
</span><span id=__span-1-34><a id=__codelineno-1-34 name=__codelineno-1-34 href=#__codelineno-1-34></a><span class=w> </span><span class=p>}</span>
</span><span id=__span-1-35><a id=__codelineno-1-35 name=__codelineno-1-35 href=#__codelineno-1-35></a><span class=w> </span><span class=p>}</span>
</span><span id=__span-1-36><a id=__codelineno-1-36 name=__codelineno-1-36 href=#__codelineno-1-36></a>
</span><span id=__span-1-37><a id=__codelineno-1-37 name=__codelineno-1-37 href=#__codelineno-1-37></a><span class=w> </span><span class=na>group_membership_claims</span><span class=w> </span><span class=o>=</span><span class=w> </span><span class=p>[</span><span class=s2>&quot;SecurityGroup&quot;</span><span class=p>]</span>
</span><span id=__span-1-38><a id=__codelineno-1-38 name=__codelineno-1-38 href=#__codelineno-1-38></a><span class=w> </span><span class=nb>optional_claims</span><span class=w> </span><span class=p>{</span>
</span><span id=__span-1-39><a id=__codelineno-1-39 name=__codelineno-1-39 href=#__codelineno-1-39></a><span class=c1> # Expose group memberships</span>
</span><span id=__span-1-40><a id=__codelineno-1-40 name=__codelineno-1-40 href=#__codelineno-1-40></a><span class=w> </span><span class=nb>id_token</span><span class=w> </span><span class=p>{</span>
</span><span id=__span-1-41><a id=__codelineno-1-41 name=__codelineno-1-41 href=#__codelineno-1-41></a><span class=w> </span><span class=na>name</span><span class=w> </span><span class=o>=</span><span class=w> </span><span class=s2>&quot;groups&quot;</span>
</span><span id=__span-1-42><a id=__codelineno-1-42 name=__codelineno-1-42 href=#__codelineno-1-42></a><span class=w> </span><span class=p>}</span>
</span><span id=__span-1-43><a id=__codelineno-1-43 name=__codelineno-1-43 href=#__codelineno-1-43></a><span class=w> </span><span class=p>}</span>
</span><span id=__span-1-44><a id=__codelineno-1-44 name=__codelineno-1-44 href=#__codelineno-1-44></a><span class=p>}</span>
</span><span id=__span-1-45><a id=__codelineno-1-45 name=__codelineno-1-45 href=#__codelineno-1-45></a>
</span><span id=__span-1-46><a id=__codelineno-1-46 name=__codelineno-1-46 href=#__codelineno-1-46></a><span class=kr>resource</span><span class=w> </span><span class=nc>&quot;azuread_application_password&quot;</span><span class=w> </span><span class=nv>&quot;headscale-application-secret&quot;</span><span class=w> </span><span class=p>{</span>
</span><span id=__span-1-47><a id=__codelineno-1-47 name=__codelineno-1-47 href=#__codelineno-1-47></a><span class=w> </span><span class=na>display_name</span><span class=w> </span><span class=o>=</span><span class=w> </span><span class=s2>&quot;Headscale Server&quot;</span>
</span><span id=__span-1-48><a id=__codelineno-1-48 name=__codelineno-1-48 href=#__codelineno-1-48></a><span class=w> </span><span class=na>application_object_id</span><span class=w> </span><span class=o>=</span><span class=w> </span><span class=nv>azuread_application.headscale.object_id</span>
</span><span id=__span-1-49><a id=__codelineno-1-49 name=__codelineno-1-49 href=#__codelineno-1-49></a><span class=p>}</span>
</span><span id=__span-1-50><a id=__codelineno-1-50 name=__codelineno-1-50 href=#__codelineno-1-50></a>
</span><span id=__span-1-51><a id=__codelineno-1-51 name=__codelineno-1-51 href=#__codelineno-1-51></a><span class=kr>resource</span><span class=w> </span><span class=nc>&quot;azuread_service_principal&quot;</span><span class=w> </span><span class=nv>&quot;headscale&quot;</span><span class=w> </span><span class=p>{</span>
</span><span id=__span-1-52><a id=__codelineno-1-52 name=__codelineno-1-52 href=#__codelineno-1-52></a><span class=w> </span><span class=na>application_id</span><span class=w> </span><span class=o>=</span><span class=w> </span><span class=nv>azuread_application.headscale.application_id</span>
</span><span id=__span-1-53><a id=__codelineno-1-53 name=__codelineno-1-53 href=#__codelineno-1-53></a><span class=p>}</span>
</span><span id=__span-1-54><a id=__codelineno-1-54 name=__codelineno-1-54 href=#__codelineno-1-54></a>
</span><span id=__span-1-55><a id=__codelineno-1-55 name=__codelineno-1-55 href=#__codelineno-1-55></a><span class=kr>resource</span><span class=w> </span><span class=nc>&quot;azuread_service_principal_password&quot;</span><span class=w> </span><span class=nv>&quot;headscale&quot;</span><span class=w> </span><span class=p>{</span>
</span><span id=__span-1-56><a id=__codelineno-1-56 name=__codelineno-1-56 href=#__codelineno-1-56></a><span class=w> </span><span class=na>service_principal_id</span><span class=w> </span><span class=o>=</span><span class=w> </span><span class=nv>azuread_service_principal.headscale.id</span>
</span><span id=__span-1-57><a id=__codelineno-1-57 name=__codelineno-1-57 href=#__codelineno-1-57></a><span class=w> </span><span class=na>end_date_relative</span><span class=w> </span><span class=o>=</span><span class=w> </span><span class=s2>&quot;44640h&quot;</span>
</span><span id=__span-1-58><a id=__codelineno-1-58 name=__codelineno-1-58 href=#__codelineno-1-58></a><span class=p>}</span>
</span><span id=__span-1-59><a id=__codelineno-1-59 name=__codelineno-1-59 href=#__codelineno-1-59></a>
</span><span id=__span-1-60><a id=__codelineno-1-60 name=__codelineno-1-60 href=#__codelineno-1-60></a><span class=kr>output</span><span class=w> </span><span class=nv>&quot;headscale_client_id&quot;</span><span class=w> </span><span class=p>{</span>
</span><span id=__span-1-61><a id=__codelineno-1-61 name=__codelineno-1-61 href=#__codelineno-1-61></a><span class=w> </span><span class=na>value</span><span class=w> </span><span class=o>=</span><span class=w> </span><span class=nv>azuread_application.headscale.application_id</span>
</span><span id=__span-1-62><a id=__codelineno-1-62 name=__codelineno-1-62 href=#__codelineno-1-62></a><span class=p>}</span>
</span><span id=__span-1-63><a id=__codelineno-1-63 name=__codelineno-1-63 href=#__codelineno-1-63></a>
</span><span id=__span-1-64><a id=__codelineno-1-64 name=__codelineno-1-64 href=#__codelineno-1-64></a><span class=kr>output</span><span class=w> </span><span class=nv>&quot;headscale_client_secret&quot;</span><span class=w> </span><span class=p>{</span>
</span><span id=__span-1-65><a id=__codelineno-1-65 name=__codelineno-1-65 href=#__codelineno-1-65></a><span class=w> </span><span class=na>value</span><span class=w> </span><span class=o>=</span><span class=w> </span><span class=nv>azuread_application_password.headscale-application-secret.value</span>
</span><span id=__span-1-66><a id=__codelineno-1-66 name=__codelineno-1-66 href=#__codelineno-1-66></a><span class=p>}</span>
</span></code></pre></div> <p>And in your headscale <code>config.yaml</code>:</p> <div class="language-yaml highlight"><span class=filename>config.yaml</span><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>&quot;https://login.microsoftonline.com/&lt;tenant-UUID&gt;/v2.0&quot;</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>&quot;&lt;client-id-from-terraform&gt;&quot;</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>&quot;&lt;client-secret-from-terraform&gt;&quot;</span>
</span><span id=__span-2-5><a id=__codelineno-2-5 name=__codelineno-2-5 href=#__codelineno-2-5></a>
</span><span id=__span-2-6><a id=__codelineno-2-6 name=__codelineno-2-6 href=#__codelineno-2-6></a><span class=w> </span><span class=c1># Optional: add &quot;groups&quot;</span>
</span><span id=__span-2-7><a id=__codelineno-2-7 name=__codelineno-2-7 href=#__codelineno-2-7></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>&quot;openid&quot;</span><span class="p p-Indicator">,</span><span class=w> </span><span class=s>&quot;profile&quot;</span><span class="p p-Indicator">,</span><span class=w> </span><span class=s>&quot;email&quot;</span><span class="p p-Indicator">]</span>
</span><span id=__span-2-8><a id=__codelineno-2-8 name=__codelineno-2-8 href=#__codelineno-2-8></a><span class=w> </span><span class=nt>extra_params</span><span class=p>:</span>
</span><span id=__span-2-9><a id=__codelineno-2-9 name=__codelineno-2-9 href=#__codelineno-2-9></a><span class=w> </span><span class=c1># Use your own domain, associated with Azure AD</span>
</span><span id=__span-2-10><a id=__codelineno-2-10 name=__codelineno-2-10 href=#__codelineno-2-10></a><span class=w> </span><span class=nt>domain_hint</span><span class=p>:</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">example.com</span>
</span><span id=__span-2-11><a id=__codelineno-2-11 name=__codelineno-2-11 href=#__codelineno-2-11></a><span class=w> </span><span class=c1># Optional: Force the Azure AD account picker</span>
</span><span id=__span-2-12><a id=__codelineno-2-12 name=__codelineno-2-12 href=#__codelineno-2-12></a><span class=w> </span><span class=nt>prompt</span><span class=p>:</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">select_account</span>
</span></code></pre></div> <h2 id=google-oauth-example>Google OAuth Example<a class=headerlink href=#google-oauth-example title="Permanent link">&para;</a></h2> <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> <h3 id=steps>Steps<a class=headerlink href=#steps title="Permanent link">&para;</a></h3> <ol> <li>Go to <a href=https://console.cloud.google.com>Google Console</a> and login or create an account if you don't have one.</li> <li>Create a project (if you don't already have one).</li> <li>On the left hand menu, go to <code>APIs and services</code> -&gt; <code>Credentials</code></li> <li>Click <code>Create Credentials</code> -&gt; <code>OAuth client ID</code></li> <li>Under <code>Application Type</code>, choose <code>Web Application</code></li> <li>For <code>Name</code>, enter whatever you like</li> <li>Under <code>Authorised redirect URIs</code>, use <code>https://example.com/oidc/callback</code>, replacing example.com with your headscale URL.</li> <li>Click <code>Save</code> at the bottom of the form</li> <li>Take note of the <code>Client ID</code> and <code>Client secret</code>, you can also download it for reference if you need it.</li> <li>Edit your headscale config, under <code>oidc</code>, filling in your <code>client_id</code> and <code>client_secret</code>: <div class="language-yaml highlight"><span class=filename>config.yaml</span><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>&quot;https://accounts.google.com&quot;</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>&quot;&quot;</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>&quot;&quot;</span>
</span><span id=__span-3-5><a id=__codelineno-3-5 name=__codelineno-3-5 href=#__codelineno-3-5></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>&quot;openid&quot;</span><span class="p p-Indicator">,</span><span class=w> </span><span class=s>&quot;profile&quot;</span><span class="p p-Indicator">,</span><span class=w> </span><span class=s>&quot;email&quot;</span><span class="p p-Indicator">]</span>
</span></code></pre></div></li> </ol> <p>You can also use <code>allowed_domains</code> and <code>allowed_users</code> to restrict the users who can authenticate.</p> <h2 id=authelia>Authelia<a class=headerlink href=#authelia title="Permanent link">&para;</a></h2> <p>Authelia since v4.39.0, has removed most claims from the <code>ID Token</code>, they are still available when application queries <a href=https://openid.net/specs/openid-connect-core-1_0.html#UserInfo>UserInfo Endpoint</a>.</p> <p>Following config restores sending 'default' claims in the <code>ID Token</code></p> <p>For more information please read: <a href=https://www.authelia.com/integration/openid-connect/openid-connect-1.0-claims/#restore-functionality-prior-to-claims-parameter>Authelia restore functionality prior to claims parameter</a></p> <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>identity_providers</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>oidc</span><span class=p>:</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>claims_policies</span><span class=p>:</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>default</span><span class=p>:</span>
</span><span id=__span-4-5><a id=__codelineno-4-5 name=__codelineno-4-5 href=#__codelineno-4-5></a><span class=w> </span><span class=nt>id_token</span><span class=p>:</span>
</span><span id=__span-4-6><a id=__codelineno-4-6 name=__codelineno-4-6 href=#__codelineno-4-6></a><span class=w> </span><span class="p p-Indicator">[</span>
</span><span id=__span-4-7><a id=__codelineno-4-7 name=__codelineno-4-7 href=#__codelineno-4-7></a><span class=w> </span><span class=s>&quot;groups&quot;</span><span class="p p-Indicator">,</span>
</span><span id=__span-4-8><a id=__codelineno-4-8 name=__codelineno-4-8 href=#__codelineno-4-8></a><span class=w> </span><span class=s>&quot;email&quot;</span><span class="p p-Indicator">,</span>
</span><span id=__span-4-9><a id=__codelineno-4-9 name=__codelineno-4-9 href=#__codelineno-4-9></a><span class=w> </span><span class=s>&quot;email_verified&quot;</span><span class="p p-Indicator">,</span>
</span><span id=__span-4-10><a id=__codelineno-4-10 name=__codelineno-4-10 href=#__codelineno-4-10></a><span class=w> </span><span class=s>&quot;alt_emails&quot;</span><span class="p p-Indicator">,</span>
</span><span id=__span-4-11><a id=__codelineno-4-11 name=__codelineno-4-11 href=#__codelineno-4-11></a><span class=w> </span><span class=s>&quot;preferred_username&quot;</span><span class="p p-Indicator">,</span>
</span><span id=__span-4-12><a id=__codelineno-4-12 name=__codelineno-4-12 href=#__codelineno-4-12></a><span class=w> </span><span class=s>&quot;name&quot;</span><span class="p p-Indicator">,</span>
</span><span id=__span-4-13><a id=__codelineno-4-13 name=__codelineno-4-13 href=#__codelineno-4-13></a><span class=w> </span><span class="p p-Indicator">]</span>
</span><span id=__span-4-14><a id=__codelineno-4-14 name=__codelineno-4-14 href=#__codelineno-4-14></a><span class=w> </span><span class=nt>clients</span><span class=p>:</span>
</span><span id=__span-4-15><a id=__codelineno-4-15 name=__codelineno-4-15 href=#__codelineno-4-15></a><span class=w> </span><span class="p p-Indicator">-</span><span class=w> </span><span class=nt>client_id</span><span class=p>:</span><span class=w> </span><span class=s>&quot;headscale&quot;</span>
</span><span id=__span-4-16><a id=__codelineno-4-16 name=__codelineno-4-16 href=#__codelineno-4-16></a><span class=w> </span><span class=nt>client_name</span><span class=p>:</span><span class=w> </span><span class=s>&quot;headscale&quot;</span>
</span><span id=__span-4-17><a id=__codelineno-4-17 name=__codelineno-4-17 href=#__codelineno-4-17></a><span class=w> </span><span class=nt>client_secret</span><span class=p>:</span><span class=w> </span><span class=s>&quot;&quot;</span>
</span><span id=__span-4-18><a id=__codelineno-4-18 name=__codelineno-4-18 href=#__codelineno-4-18></a><span class=w> </span><span class=nt>public</span><span class=p>:</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">false</span>
</span><span id=__span-4-19><a id=__codelineno-4-19 name=__codelineno-4-19 href=#__codelineno-4-19></a><span class=w> </span><span class=nt>claims_policy</span><span class=p>:</span><span class=w> </span><span class=s>&quot;default&quot;</span>
</span><span id=__span-4-20><a id=__codelineno-4-20 name=__codelineno-4-20 href=#__codelineno-4-20></a><span class=w> </span><span class=nt>authorization_policy</span><span class=p>:</span><span class=w> </span><span class=s>&quot;two_factor&quot;</span>
</span><span id=__span-4-21><a id=__codelineno-4-21 name=__codelineno-4-21 href=#__codelineno-4-21></a><span class=w> </span><span class=nt>require_pkce</span><span class=p>:</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">true</span>
</span><span id=__span-4-22><a id=__codelineno-4-22 name=__codelineno-4-22 href=#__codelineno-4-22></a><span class=w> </span><span class=nt>pkce_challenge_method</span><span class=p>:</span><span class=w> </span><span class=s>&quot;S256&quot;</span>
</span><span id=__span-4-23><a id=__codelineno-4-23 name=__codelineno-4-23 href=#__codelineno-4-23></a><span class=w> </span><span class=nt>redirect_uris</span><span class=p>:</span>
</span><span id=__span-4-24><a id=__codelineno-4-24 name=__codelineno-4-24 href=#__codelineno-4-24></a><span class=w> </span><span class="p p-Indicator">-</span><span class=w> </span><span class=s>&quot;https://headscale.example.com/oidc/callback&quot;</span>
</span><span id=__span-4-25><a id=__codelineno-4-25 name=__codelineno-4-25 href=#__codelineno-4-25></a><span class=w> </span><span class=nt>scopes</span><span class=p>:</span>
</span><span id=__span-4-26><a id=__codelineno-4-26 name=__codelineno-4-26 href=#__codelineno-4-26></a><span class=w> </span><span class="p p-Indicator">-</span><span class=w> </span><span class=s>&quot;openid&quot;</span>
</span><span id=__span-4-27><a id=__codelineno-4-27 name=__codelineno-4-27 href=#__codelineno-4-27></a><span class=w> </span><span class="p p-Indicator">-</span><span class=w> </span><span class=s>&quot;profile&quot;</span>
</span><span id=__span-4-28><a id=__codelineno-4-28 name=__codelineno-4-28 href=#__codelineno-4-28></a><span class=w> </span><span class="p p-Indicator">-</span><span class=w> </span><span class=s>&quot;groups&quot;</span>
</span><span id=__span-4-29><a id=__codelineno-4-29 name=__codelineno-4-29 href=#__codelineno-4-29></a><span class=w> </span><span class="p p-Indicator">-</span><span class=w> </span><span class=s>&quot;email&quot;</span>
</span><span id=__span-4-30><a id=__codelineno-4-30 name=__codelineno-4-30 href=#__codelineno-4-30></a><span class=w> </span><span class=nt>userinfo_signed_response_alg</span><span class=p>:</span><span class=w> </span><span class=s>&quot;none&quot;</span>
</span><span id=__span-4-31><a id=__codelineno-4-31 name=__codelineno-4-31 href=#__codelineno-4-31></a><span class=w> </span><span class=nt>token_endpoint_auth_method</span><span class=p>:</span><span class=w> </span><span class=s>&quot;client_secret_basic&quot;</span>
</span></code></pre></div> </article> </div> <script>var target=document.getElementById(location.hash.slice(1));target&&target.name&&(target.checked=target.name.startsWith("__tabbed_"))</script> </div> <button type=button class="md-top md-icon" data-md-component=top hidden> <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> Back to top </button> </main> <footer class=md-footer> <nav class="md-footer__inner md-grid" aria-label=Footer> <a href=../configuration/ class="md-footer__link md-footer__link--prev" aria-label="Previous: Configuration"> <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> Configuration </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 &copy; 2025 Headscale authors </div> Made with <a href=https://squidfunk.github.io/mkdocs-material/ target=_blank rel=noopener> Material for MkDocs </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 496 512"><!-- Font Awesome Free 6.7.2 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 2024 Fonticons, Inc.--><path d="M165.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.9M244.8 8C106.1 8 0 113.3 0 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.1C428.2 457.8 496 362.9 496 252 496 113.3 383.5 8 244.8 8M97.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 2.3 3.9 1.6 1 3.6.7 4.3-.7.7-1.3-.3-2.9-2.3-3.9-2-.6-3.6-.3-4.3.7m32.4 35.6c-1.6 1.3-1 4.3 1.3 6.2 2.3 2.3 5.2 2.6 6.5 1 1.3-1.3.7-4.3-1.3-6.2-2.2-2.3-5.2-2.6-6.5-1m-11.4-14.7c-1.6 1-1.6 3.6 0 5.9s4.3 3.3 5.6 2.3c1.6-1.3 1.6-3.9 0-6.2-1.4-2.3-4-3.3-5.6-2"/></svg> </a> <a href=https://ko-fi.com/headscale target=_blank rel=noopener title=ko-fi.com class=md-social__link> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M2 21h18v-2H2M20 8h-2V5h2m0-2H4v10a4 4 0 0 0 4 4h6a4 4 0 0 0 4-4v-3h2a2 2 0 0 0 2-2V5a2 2 0 0 0-2-2"/></svg> </a> <a href=https://github.com/juanfont/headscale/pkgs/container/headscale target=_blank rel=noopener title=github.com class=md-social__link> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 640 512"><!-- Font Awesome Free 6.7.2 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 2024 Fonticons, Inc.--><path d="M349.9 236.3h-66.1v-59.4h66.1zm0-204.3h-66.1v60.7h66.1zm78.2 144.8H362v59.4h66.1zm-156.3-72.1h-66.1v60.1h66.1zm78.1 0h-66.1v60.1h66.1zm276.8 100c-14.4-9.7-47.6-13.2-73.1-8.4-3.3-24-16.7-44.9-41.1-63.7l-14-9.3-9.3 14c-18.4 27.8-23.4 73.6-3.7 103.8-8.7 4.7-25.8 11.1-48.4 10.7H2.4c-8.7 50.8 5.8 116.8 44 162.1 37.1 43.9 92.7 66.2 165.4 66.2 157.4 0 273.9-72.5 328.4-204.2 21.4.4 67.6.1 91.3-45.2 1.5-2.5 6.6-13.2 8.5-17.1zm-511.1-27.9h-66v59.4h66.1v-59.4zm78.1 0h-66.1v59.4h66.1zm78.1 0h-66.1v59.4h66.1zm-78.1-72.1h-66.1v60.1h66.1z"/></svg> </a> <a href=https://discord.gg/c84AZQhmpx target=_blank rel=noopener title=discord.gg class=md-social__link> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 640 512"><!-- Font Awesome Free 6.7.2 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 Line truncated
<!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/development/ref/oidc/ rel=canonical><link href=../configuration/ rel=prev><link href=../routes/ rel=next><link rel=icon href=../../assets/favicon.png><meta name=generator content="mkdocs-1.6.1, mkdocs-material-9.6.15"><title>OpenID Connect - Headscale</title><link rel=stylesheet href=../../assets/stylesheets/main.342714a4.min.css><link rel=stylesheet href=../../assets/stylesheets/palette.06af60db.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/development/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/development/ref/oidc/ property=og:url><meta name=twitter:card content=summary_large_image><meta name=twitter:title content="OpenID Connect - Headscale"><meta name=twitter:description content="An open source, self-hosted implementation of the Tailscale control server."><meta name=twitter:image content=https://juanfont.github.io/headscale/development/assets/images/social/ref/oidc.png></head> <body dir=ltr data-md-color-scheme=default data-md-color-primary=white data-md-color-accent=indigo> <input class=md-toggle data-md-toggle=drawer type=checkbox id=__drawer autocomplete=off> <input class=md-toggle data-md-toggle=search type=checkbox id=__search autocomplete=off> <label class=md-overlay for=__drawer></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=../../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 data-md-color-scheme=default data-md-color-primary=white data-md-color-accent=indigo aria-label="Switch to dark mode" type=radio name=__palette id=__palette_0> <label class="md-header__button md-icon" title="Switch to dark mode" for=__palette_1 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 data-md-color-scheme=slate data-md-color-primary=indigo data-md-color-accent=indigo aria-label="Switch to light mode" type=radio name=__palette id=__palette_1> <label class="md-header__button md-icon" title="Switch to light mode" for=__palette_0 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 18c-.89 0-1.74-.2-2.5-.55C11.56 16.5 13 14.42 13 12s-1.44-4.5-3.5-5.45C10.26 6.2 11.11 6 12 6a6 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> </form> <script>var palette=__md_get("__palette");if(palette&&palette.color){if("(prefers-color-scheme)"===palette.color.media){var media=matchMedia("(prefers-color-scheme: light)"),input=document.querySelecLine 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>&quot;https://sso.example.com&quot;</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>&quot;headscale&quot;</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>&quot;generated-secret&quot;</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">&para;</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>&quot;https://sso.example.com&quot;</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>&quot;headscale&quot;</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>&quot;generated-secret&quot;</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">&para;</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>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>&quot;https://sso.example.com&quot;</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>&quot;headscale&quot;</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>&quot;generated-secret&quot;</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>&quot;example.com&quot;</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>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>&quot;https://sso.example.com&quot;</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>&quot;headscale&quot;</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>&quot;generated-secret&quot;</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>&quot;alice@example.com&quot;</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>&quot;bob@example.net&quot;</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>&quot;https://sso.example.com&quot;</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>&quot;headscale&quot;</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>&quot;generated-secret&quot;</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>&quot;openid&quot;</span><span class="p p-Indicator">,</span><span class=w> </span><span class=s>&quot;profile&quot;</span><span class="p p-Indicator">,</span><span class=w> </span><span class=s>&quot;email&quot;</span><span class="p p-Indicator">,</span><span class=w> </span><span class=s>&quot;groups&quot;</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>&quot;headscale_users&quot;</span>
</span></span></code></pre></div> </div> </div> </div> <h3 id=customize-node-expiration>Customize node expiration<a class=headerlink href=#customize-node-expiration title="Permanent link">&para;</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> <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-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>&quot;https://sso.example.com&quot;</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>&quot;headscale&quot;</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>&quot;generated-secret&quot;</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>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 reauthentication.</p> <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>oidc</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=w> </span><span class=nt>issuer</span><span class=p>:</span><span class=w> </span><span class=s>&quot;https://sso.example.com&quot;</span>
</span><span id=__span-6-3><a id=__codelineno-6-3 name=__codelineno-6-3 href=#__codelineno-6-3></a><span class=w> </span><span class=nt>client_id</span><span class=p>:</span><span class=w> </span><span class=s>&quot;headscale&quot;</span>
</span><span id=__span-6-4><a id=__codelineno-6-4 name=__codelineno-6-4 href=#__codelineno-6-4></a><span class=w> </span><span class=nt>client_secret</span><span class=p>:</span><span class=w> </span><span class=s>&quot;generated-secret&quot;</span>
</span><span id=__span-6-5><a id=__codelineno-6-5 name=__codelineno-6-5 href=#__codelineno-6-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: <div class="language-console 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=go>headscale node expire -i &lt;NODE_ID&gt;</span>
</span></code></pre></div></p> </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">&para;</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> <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 username <code>ssmith</code> has to be written as <code>ssmith@</code> to be correctly identified as user within the policy.</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> <h2 id=supported-oidc-claims>Supported OIDC claims<a class=headerlink href=#supported-oidc-claims title="Permanent link">&para;</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 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><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">&para;</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 <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">&para;</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">&para;</a></h3> <p>Authelia is fully supported by Headscale.</p> <h4 id=additional-configuration-to-authorize-users-based-on-filters>Additional configuration to authorize users based on filters<a class=headerlink href=#additional-confiLine truncated