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

[masterwishx]

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

[nblock]

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.

[masterwishx]

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": "[email protected]",
    "email_verified": true,
    "name": "DaRK AnGeL",
    "given_name": "DaRK AnGeL",
    "preferred_username": "masterwishx",
    "nickname": "masterwishx",
    "groups": [
        "authentik Admins",
        "headscale Users"
    ]
}