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

[PR #1934] [CLOSED] re-construct OIDC config and flatten keycloak groups #2405

New Issue
Closed
opened 2025-12-29 03:21:06 +01:00 by adam · 0 comments
adam commented 2025-12-29 03:21:06 +01:00
Owner
Copy Link

📋 Pull Request Information

Original PR: https://github.com/juanfont/headscale/pull/1934
Author: @IamTaoChen
Created: 5/9/2024
Status: ❌ Closed

Base: main ← Head: dev_oidc

📝 Commits (8)

📊 Changes

6 files changed (+299 additions, -136 deletions)

View changed files

📝 config-example.yaml (+54 -38)
📝 docs/oidc.md (+54 -28)
📝 hscontrol/oidc.go (+66 -12)
📝 hscontrol/suite_test.go (+3 -1)
📝 hscontrol/types/config.go (+116 -54)
📝 integration/auth_oidc_test.go (+6 -3)

📄 Description

  • use the claims_map to extract the designed information by the name which was a fixed map. the username needs to be careful because now OIDC uses claim.username as USERNAME, if you want to keep same as before (Email), please set username=email .
  • combine allowed_domains,allowed_groups,allowed_userd to allowed
  • add misc to save the random thing. if you set misc.flatten_groups=true, it will try to flatten the groups. this is for keycloak which group format is "/group/subgroup".
  • The misc.strip_email_domain only works when the username is email format, e.g claims_map.usename=email

new OIDC config

oidc:
  only_start_if_oidc_is_available: true
  issuer: "https://auth.example.com/auth/realms/master"
  client_id: "YOUR_CLIENT_ID"
  client_secret: "YOUR_SECRET"
  #   # 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"
  #   # 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"]

  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

  #   extra_params:
  #     domain_hint: example.com

  # allowd:
  #   domains:
  #     # List allowed principal domains and/or users. If an authenticated user's domain is not in this list, the
  #     # authentication request will be rejected.
  #     - example.com
  #   groups:
  #     # List allowed groups. 
  #     - admins
  #   users:
  #     - admin@example.com

  #  Map claims from the OIDC token to the user object
  claims_map:
    name: name
    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: "/"
  • have read the CONTRIBUTING.md file
  • raised a GitHub issue or discussed it on the projects chat beforehand
  • added unit tests
  • added integration tests
  • updated documentation if needed
  • updated CHANGELOG.md

🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.

## 📋 Pull Request Information **Original PR:** https://github.com/juanfont/headscale/pull/1934 **Author:** [@IamTaoChen](https://github.com/IamTaoChen) **Created:** 5/9/2024 **Status:** ❌ Closed **Base:** `main` ← **Head:** `dev_oidc` --- ### 📝 Commits (8) - [`890d6e7`](https://github.com/juanfont/headscale/commit/890d6e73fbc5fd93f22ebf9d84c5b723b56381dd) re-construct oidc config - [`51a257b`](https://github.com/juanfont/headscale/commit/51a257b70061802295c4dbd350e2d6d84908546f) change var name - [`77c6bca`](https://github.com/juanfont/headscale/commit/77c6bcaccae645fe015c6c22aaa3e75bfeeb4c57) update example - [`bd78f56`](https://github.com/juanfont/headscale/commit/bd78f564b9210cf41caf3c70c4340dadac3a10d8) fix bug - [`1e128fc`](https://github.com/juanfont/headscale/commit/1e128fc854905e21691e925aca356cc936cad55e) username=email - [`d211b93`](https://github.com/juanfont/headscale/commit/d211b930eecc7effd0a47f24d2263e800b18f646) fix spell error: allowd -> allowed - [`901613a`](https://github.com/juanfont/headscale/commit/901613a24b0f2a1e44a32b4313f73a4e2af0075c) Merge branch 'main' into dev_oidc - [`39b34ad`](https://github.com/juanfont/headscale/commit/39b34ad1cb93f99851ed126bf3cd4f7b8407f31e) update oidc README.md ### 📊 Changes **6 files changed** (+299 additions, -136 deletions) <details> <summary>View changed files</summary> 📝 `config-example.yaml` (+54 -38) 📝 `docs/oidc.md` (+54 -28) 📝 `hscontrol/oidc.go` (+66 -12) 📝 `hscontrol/suite_test.go` (+3 -1) 📝 `hscontrol/types/config.go` (+116 -54) 📝 `integration/auth_oidc_test.go` (+6 -3) </details> ### 📄 Description <!-- Headscale is "Open Source, acknowledged contribution", this means that any contribution will have to be discussed with the Maintainers before being submitted. This model has been chosen to reduce the risk of burnout by limiting the maintenance overhead of reviewing and validating third-party code. Headscale is open to code contributions for bug fixes without discussion. If you find mistakes in the documentation, please submit a fix to the documentation. --> * use the `claims_map` to extract the designed information by the name which was a fixed map. the `username` needs to be careful because now OIDC uses `claim.username` as USERNAME, if you want to keep same as before (Email), please set `username=email` . * combine `allowed_domains`,`allowed_groups`,`allowed_userd` to `allowed` * add `misc` to save the random thing. if you set `misc.flatten_groups=true`, it will try to flatten the groups. this is for keycloak which group format is "/group/subgroup". * The `misc.strip_email_domain` only works when the `username` is email format, e.g `claims_map.usename=email` new OIDC config ```yaml oidc: only_start_if_oidc_is_available: true issuer: "https://auth.example.com/auth/realms/master" client_id: "YOUR_CLIENT_ID" client_secret: "YOUR_SECRET" # # 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" # # 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"] 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 # extra_params: # domain_hint: example.com # allowd: # domains: # # List allowed principal domains and/or users. If an authenticated user's domain is not in this list, the # # authentication request will be rejected. # - example.com # groups: # # List allowed groups. # - admins # users: # - admin@example.com # Map claims from the OIDC token to the user object claims_map: name: name 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: "/" ``` <!-- Please tick if the following things apply. You… --> - [x] have read the [CONTRIBUTING.md](./CONTRIBUTING.md) file - [ ] raised a GitHub issue or discussed it on the projects chat beforehand - [ ] added unit tests - [ ] added integration tests - [ ] updated documentation if needed - [ ] updated CHANGELOG.md <!-- If applicable, please reference the issue using `Fixes #XXX` and add tests to cover your new code. --> --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>
adam added the pull-request label 2025-12-29 03:21:06 +01:00
adam closed this issue 2025-12-29 03:21:06 +01:00
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 pull-request
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#2405
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?