mirror of
https://github.com/juanfont/headscale.git
synced 2026-10-18 12:36:32 +09:00
Deployed c2a58a30 to development with MkDocs 1.6.1 and mike 2.1.3
This commit is contained in:
1 parent
18197a86d4
commit
01826c376a
39 files changed
+125
-92
No files matched your search
@@ -1,4 +1,4 @@
|
||||
<!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.21"><title>OpenID Connect - Headscale</title><link rel=stylesheet href=../../assets/stylesheets/main.2a3383ac.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
|
||||
<!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.22"><title>OpenID Connect - Headscale</title><link rel=stylesheet href=../../assets/stylesheets/main.84d31ad4.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>"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>
|
||||
@@ -39,4 +39,4 @@
|
||||
</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>"generated-secret"</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 <NODE_ID></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">¶</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">¶</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 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">¶</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">¶</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 hrefLine truncated
|
||||
</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">¶</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">¶</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 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">¶</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">¶</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 hrefLine truncated
|
||||
Reference in new issue
Block a user