From 39b34ad1cb93f99851ed126bf3cd4f7b8407f31e Mon Sep 17 00:00:00 2001
From: Tao Chen <tachen@phys.ethz.ch>
Date: Fri, 17 May 2024 20:40:05 +0200
Subject: [PATCH] update oidc README.md

---
 docs/oidc.md | 80 ++++++++++++++++++++++++++++++++++------------------
 1 file changed, 53 insertions(+), 27 deletions(-)

diff --git a/docs/oidc.md b/docs/oidc.md
index c8746bb..922dc70 100644
--- a/docs/oidc.md
+++ b/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
-  # set HEADSCALE_OIDC_CLIENT_SECRET to the required value
-
+  # client_secret_path: "${CREDENTIALS_DIRECTORY}/oidc_client_secret"
+  # client_secret and client_secret_path are mutually exclusive.
+  #
   # 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
+    extra_params:
+      domain_hint: example.com
+
+  expiry:
+    #
+    # Use the expiry from the token received from OpenID when the user logged
+    # in, this will typically lead to frequent need to reauthenticate and should
+    # only been enabled if you know what you are doing.
+    # Note: enabling this will cause `oidc.expiry.fixed_time` to be ignored.
+    from_token: false
+    #
+    # The amount of time from a node is authenticated with OpenID until it
+    # 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: "/"
 
-  # Optional: 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
-  # Optional. Note that groups from Keycloak have a leading '/'.
-  allowed_groups:
-    - /headscale
-  # Optional.
-  allowed_users:
-    - alice@example.com
 
-  # 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
 ```
 
 ## 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.