starred/headscale
1
0
Fork 0
mirror of https://github.com/juanfont/headscale.git synced 2026-01-11 20:00:28 +01:00
Code Issues 98 Packages Projects Releases 10 Wiki Activity

[Feature] [Docs] update OIDC documentation for 0.24.0+ #883

New Issue
Closed
opened 2025-12-29 02:25:11 +01:00 by adam · 2 comments
adam commented 2025-12-29 02:25:11 +01:00
Owner
Copy Link

Originally created by @masterwishx on GitHub (Dec 15, 2024).

Originally assigned to: @nblock on GitHub.

Use case

updated to 24.0beta1 all fine.
should we change in config for OIDC ?
scope: ["openid", "profile", "email"]
to add preferred_username,name,picture ? using Authentik.
We should update the documentation for this.

Description

Update documentation for OIDC in v 24.0

Contribution

  • I can write the design doc for this feature
  • I can contribute this feature

How can it be implemented?

Update documentation I can give my example of current using Authentik

Originally created by @masterwishx on GitHub (Dec 15, 2024). Originally assigned to: @nblock on GitHub. ### Use case updated to 24.0beta1 all fine. should we change in config for OIDC ? `scope: ["openid", "profile", "email"]` to add `preferred_username,name,picture` ? using Authentik. We should update the documentation for this. ### Description Update documentation for OIDC in v 24.0 ### Contribution - [ ] I can write the design doc for this feature - [ ] I can contribute this feature ### How can it be implemented? Update documentation I can give my example of current using Authentik
adam added the enhancementno-stale-botdocumentation labels 2025-12-29 02:25:11 +01:00
adam closed this issue 2025-12-29 02:25:12 +01:00
adam commented 2025-12-29 02:25:12 +01:00
Author
Owner
Copy Link

@nblock commented on GitHub (Dec 17, 2024):

I plan to update the current OIDC documentation and provide more structure. It should probably be structured like this:

  • Short introduction, possibly with a list of known limitations
  • Generic setup instructions: the OIDC configuration of Headscale should be described once with a description of required parameters (issuer, client_id, client_secret or client_secret_path) and some useful optional parameters such as scope.
  • IdP specific instructions where we could rehash parts of the existing configuration.

Anything missing that should be covered?

@masterwishx it'd be great if you could share your Authentik configuration, thx.

@nblock commented on GitHub (Dec 17, 2024): I plan to update the current OIDC documentation and provide more structure. It should probably be structured like this: * Short introduction, possibly with a list of known limitations * Generic setup instructions: the OIDC configuration of Headscale should be described once with a description of required parameters (`issuer`, `client_id`, `client_secret` or `client_secret_path`) and some useful optional parameters such as `scope`. * IdP specific instructions where we could rehash parts of the existing configuration. Anything missing that should be covered? @masterwishx it'd be great if you could share your Authentik configuration, thx.
adam commented 2025-12-29 02:25:12 +01:00
Author
Owner
Copy Link

@masterwishx commented on GitHub (Dec 17, 2024):

config.yml

oidc:
  only_start_if_oidc_is_available: true
  issuer: "https://auth.mysite.com/application/o/headscale/"
  client_id: "abcdhkjhjkhkjhk.reducted...."
  client_secret: "abdslkjsdkjssdkj.....reducted.."
  
  expiry: 180d
  
  scope: ["openid", "profile", "email"]    //not sure if we need also `offline_access` ?
  
  allowed_groups:
    - headscale Users

Starting with authentik 2024.2, applications only receive an access token. To receive a refresh token, both applications and authentik must be configured to request the offline_access scope. In authentik this can be done by selecting the offline_access Scope mapping in the provider settings.

OAuth2/OpenID Provider = Headscale OIDC Auth
  
OpenID Configuration URL 
https://auth.myserver.com/application/o/headscale/.well-known/openid-configuration

OpenID Configuration Issuer 
https://auth.myserver.com/application/o/headscale/

Authorize URL 
https://auth.myserver.com/application/o/authorize/

Token URL 
https://auth.myserver.com/application/o/token/

Userinfo URL 
https://auth.myserver.com/application/o/userinfo/

Logout URL 
https://auth.myserver.com/application/o/headscale/end-session/

JWKS URL 
https://auth.myserver.com/application/o/headscale/jwks/

Subject mode:  Based on User's ID 

Redirect URIs
strict: https://headscale.mysite.com/oidc/callback

Application

Name *
Headscale
Application's display Name.

Slug *
headscale
Internal application name used in URLs.

Provider
Headscale OIDC Auth

Policy/Group/User Binding for Aplication: 

Group Info
Name
headscale Users

Provider privew : 

Preview for user
Select an object.
{
    "iss": "https://auth.myserver.com/application/o/headscale/",
    "sub": "1",
    "aud": "abcdss ....reducted..",
    "exp": 17344..reducted...,
    "iat": 17344..reducted...,
    "auth_time": 1734..reducted...,
    "acr": "goauthentik.io/providers/oauth2/default",
    "email": "masterwishx@maymail.com",
    "email_verified": true,
    "name": "DaRK AnGeL",
    "given_name": "DaRK AnGeL",
    "preferred_username": "masterwishx",
    "nickname": "masterwishx",
    "groups": [
        "authentik Admins",
        "headscale Users"
    ]
}
@masterwishx commented on GitHub (Dec 17, 2024): config.yml ``` oidc: only_start_if_oidc_is_available: true issuer: "https://auth.mysite.com/application/o/headscale/" client_id: "abcdhkjhjkhkjhk.reducted...." client_secret: "abdslkjsdkjssdkj.....reducted.." expiry: 180d scope: ["openid", "profile", "email"] //not sure if we need also `offline_access` ? allowed_groups: - headscale Users ``` Starting with authentik 2024.2, applications only receive an access token. To receive a refresh token, both applications and authentik must be configured to request the offline_access scope. In authentik this can be done by selecting the offline_access Scope mapping in the provider settings. ``` OAuth2/OpenID Provider = Headscale OIDC Auth OpenID Configuration URL https://auth.myserver.com/application/o/headscale/.well-known/openid-configuration OpenID Configuration Issuer https://auth.myserver.com/application/o/headscale/ Authorize URL https://auth.myserver.com/application/o/authorize/ Token URL https://auth.myserver.com/application/o/token/ Userinfo URL https://auth.myserver.com/application/o/userinfo/ Logout URL https://auth.myserver.com/application/o/headscale/end-session/ JWKS URL https://auth.myserver.com/application/o/headscale/jwks/ Subject mode: Based on User's ID Redirect URIs strict: https://headscale.mysite.com/oidc/callback ``` ``` Application Name * Headscale Application's display Name. Slug * headscale Internal application name used in URLs. Provider Headscale OIDC Auth ``` ``` Policy/Group/User Binding for Aplication: Group Info Name headscale Users ``` ``` Provider privew : Preview for user Select an object. { "iss": "https://auth.myserver.com/application/o/headscale/", "sub": "1", "aud": "abcdss ....reducted..", "exp": 17344..reducted..., "iat": 17344..reducted..., "auth_time": 1734..reducted..., "acr": "goauthentik.io/providers/oauth2/default", "email": "masterwishx@maymail.com", "email_verified": true, "name": "DaRK AnGeL", "given_name": "DaRK AnGeL", "preferred_username": "masterwishx", "nickname": "masterwishx", "groups": [ "authentik Admins", "headscale Users" ] } ```
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
CLI
DERP
DNS
Nix
OIDC
SSH
bug
database
documentation
duplicate
enhancement
faq
good first issue
grants
help wanted
might-come
needs design doc
needs investigation
no-stale-bot
out of scope
performance
policy 📝
pull-request
Mirrored from GitHub Pull Request
 question
regression
routes
stale
tags
tailscale-feature-gap
well described ❤️
wontfix
No Label documentation enhancement no-stale-bot
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
adam
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: starred/headscale#883
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?