update oidc README.md

docs/oidc.md

@@ -13,43 +13,69 @@ In your `config.yaml`, customize this to your liking:
 
 ```yaml
 oidc:
-  # Block further startup until the OIDC provider is healthy and available
   only_start_if_oidc_is_available: true
-  # Specified by your OIDC provider
   issuer: "https://your-oidc.issuer.com/path"
-  # Specified/generated by your OIDC provider
   client_id: "your-oidc-client-id"
   client_secret: "your-oidc-client-secret"
-  # alternatively, set `client_secret_path` to read the secret from the file.
+  # Alternatively, set `client_secret_path` to read the secret from the file.
   # It resolves environment variables, making integration to systemd's
   # `LoadCredential` straightforward:
   # client_secret_path: "${CREDENTIALS_DIRECTORY}/oidc_client_secret"
-  # as third option, it's also possible to load the oidc secret from environment variables
+  # client_secret and client_secret_path are mutually exclusive.
-  # set HEADSCALE_OIDC_CLIENT_SECRET to the required value
+  #
-
   # Customize the scopes used in the OIDC flow, defaults to "openid", "profile" and "email" and add custom query
   # parameters to the Authorize Endpoint request. Scopes default to "openid", "profile" and "email".
   scope: ["openid", "profile", "email", "custom"]
-  # Optional: Passed on to the browser login request – used to tweak behaviour for the OIDC provider
     extra_params:
       domain_hint: example.com
 
-  # Optional: List allowed principal domains and/or users. If an authenticated user's domain is not in this list,
+  expiry:
-  # the authentication request will be rejected.
+    #
-  allowed_domains:
+    # Use the expiry from the token received from OpenID when the user logged
-    - example.com
+    # in, this will typically lead to frequent need to reauthenticate and should
-  # Optional. Note that groups from Keycloak have a leading '/'.
+    # only been enabled if you know what you are doing.
-  allowed_groups:
+    # Note: enabling this will cause `oidc.expiry.fixed_time` to be ignored.
-    - /headscale
+    from_token: false
-  # Optional.
+    #
-  allowed_users:
+    # The amount of time from a node is authenticated with OpenID until it
-    - alice@example.com
+    # expires and needs to reauthenticate.
+    # Setting the value to "0" will mean no expiry.
+    fixed_time: 180d
 
+  # # List allowed principal domains and/or users. If an authenticated user's domain is not in this list, the
+  # # authentication request will be rejected.
+  allowed:
+    domains:
+      - example.com
+    groups:
+      - admins
+    users:
+      - admin@example.com
+
+  #  Map claims from the OIDC token to the user object
+  claims_map:
+    name: name
+    username: email
+   # username: preferred_username
+    email: email
+    groups: groups
+    
+
+  #  some random configuration
+  misc:
+    # if the username is set to `email` then `strip_email_domain` is valid
     # If `strip_email_domain` is set to `true`, the domain part of the username email address will be removed.
     # This will transform `first-name.last-name@example.com` to the user `first-name.last-name`
     # If `strip_email_domain` is set to `false` the domain part will NOT be removed resulting to the following
     # user: `first-name.last-name.example.com`
     strip_email_domain: true
+    # If `flatten_groups` is set to `true`, the groups claim will be flattened to a single level.
+    # this is used for keycloak where the groups are nested. the groups format from keycloak is `group1/subgroup1/subgroup2`
+    flatten_groups: true
+    # If `flatten_splitter` is set to a string, the groups claim will be split by the string and flattened to a single level.
+    flatten_splitter: "/"
+
+
 ```
 
 ## Azure AD example
@@ -171,4 +197,4 @@ oidc:
   scope: ["openid", "profile", "email"]
 ```
 
-You can also use `allowed_domains` and `allowed_users` to restrict the users who can authenticate.
+You can also use `allowed.domains` and `allowed.users` to restrict the users who can authenticate.