Skip to content

Refactor OpenID Connect documentation #2625

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Merged
nblock merged 1 commit into from
Jul 4, 2025
Merged

Refactor OpenID Connect documentation #2625

nblock merged 1 commit into from
Jul 4, 2025

Conversation

@nblock
Copy link
Collaborator

@nblock nblock commented May 24, 2025 •
edited
Loading

Please see commit messages for details.

Preview: https://nblock.github.io/headscale/ref/oidc/

  • 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

@nblock nblock requested a review from kradalby May 24, 2025 10:57
@ghost
Copy link

ghost commented May 24, 2025 •
edited by ghost
Loading

Pull Request Revisions

RevisionDescription
r7
Added Google OAuth username limitation noteAdded a warning note explaining that Google OAuth does not provide preferred_username claim, resulting in blank username in Headscale
r6
Refactored OpenID Connect documentationUpdated and improved documentation for OpenID Connect configuration and implementation in the project
r5
OIDC documentation updated and refinedComprehensive documentation refinement for OIDC, including improved formatting, clarified sections, and updated provider-specific configuration guidance
r4
Updated Authelia OIDC claims documentationExpanded documentation on Authelia OIDC claims, clarifying configuration for authorizing users based on domain, email, or groups
r3
Updated Authelia OIDC documentation sectionSimplified Authelia documentation, added note about group claims configuration for authorization filtering
r2
Improved OIDC documentation and configurationExtensively updated OpenID Connect documentation with detailed configuration examples, provider-specific notes, and expanded explanation of OIDC features in Headscale
r1
Enhanced OpenID Connect configuration documentationComprehensive updates to OIDC documentation including configuration details, user authorization methods, supported claims, and identity provider specific guidance
☑️ AI review skipped after 5 revisions, comment with `/review` to review again
Help React with emojis to give feedback on AI-generated reviews:
  • 👍 means the feedback was helpful and actionable
  • 👎 means the feedback was incorrect or unhelpful
💬 Replying to feedback with a comment helps us improve the system. Your input also contributes to shaping future interactions with the AI reviewer.

We'd love to hear from you—reach out anytime at [email protected].

@nblock nblock force-pushed the oidc branch 4 times, most recently from 36c9726 to 91e9406 Compare May 29, 2025 12:45
@nblock nblock marked this pull request as ready for review May 29, 2025 12:48
@nblock nblock requested a review from ohdearaugustin as a code owner May 29, 2025 12:48
@nblock
Refactor OpenID Connect documentation
ad5386e 
Restructure and rewrite the OpenID Connect documentation. Start from the
most minimal configuration and describe what needs to be done both in
Headscale and the identity provider. Describe additional features such
as PKCE and authorization filters in a generic manner with examples.

Document how Headscale populates its user profile and how it relates to
OIDC claims. This is a revised version from the table in the changelog.
Document the validation rules for fields and extend known limitations.

Sort the provider specific section alphabetically and add a section for
Authelia, Authentik, Kanidm and Keycloak. Also simplify and rename Azure
to Entra ID.

Update the description for the oidc section in the example
configuration. Give a short explanation of each configuration setting.

All documentend features were tested with Headscale 0.26 (using a fresh
database each time) using the following identity providers:

* Authelia
* Authentik
* Kanidm
* Keycloak

Fixes: juanfont#2295
@nblock nblock requested a review from juanfont as a code owner June 24, 2025 06:39
kradalby
kradalby approved these changes Jul 4, 2025
View reviewed changes
Copy link
Collaborator

@kradalby kradalby left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Great!

@nblock nblock merged commit d461db3 into juanfont:main Jul 4, 2025
144 of 149 checks passed
@nblock nblock deleted the oidc branch July 4, 2025 08:51
@chenrui333 chenrui333 mentioned this pull request Oct 27, 2025
Open
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@kradalby kradalby kradalby approved these changes

@ohdearaugustin ohdearaugustin Awaiting requested review from ohdearaugustin ohdearaugustin is a code owner

@juanfont juanfont Awaiting requested review from juanfont juanfont is a code owner

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@nblock @kradalby