starred/headscale
1
0
Fork 0
mirror of https://github.com/juanfont/headscale.git synced 2026-01-11 11:50:30 +01:00
Code Issues 98 Packages Projects Releases 10 Wiki Activity

[PR #2704] Feature/planetexpress/OIDC refresh tokens #2813

New Issue
Open
opened 2025-12-29 04:19:05 +01:00 by adam · 0 comments
adam commented 2025-12-29 04:19:05 +01:00
Owner
Copy Link

📋 Pull Request Information

Original PR: https://github.com/juanfont/headscale/pull/2704
Author: @mazlumtoprak
Created: 7/24/2025
Status: 🔄 Open

Base: main ← Head: feature/planetexpress/oidc-refresh-tokens

📝 Commits (5)

  • 7d3e7a2 Fix /machine/map endpoint vulnerability (#2642)
  • fd8bd3f implement oauth2 refresh tokens with background refreshing
  • 46816c8 few improvements: clean database table, more cfg, exact db queries by nodeID
  • da57cf4 fix user reference unit test, fmt
  • a0007a7 rebase and refactor to new state mgmt

📊 Changes

14 files changed (+1442 additions, -16 deletions)

View changed files

📝 CHANGELOG.md (+7 -1)
📝 config-example.yaml (+17 -6)
📝 docs/ref/oidc.md (+7 -1)
📝 hscontrol/app.go (+40 -0)
📝 hscontrol/db/db.go (+73 -1)
📝 hscontrol/db/node.go (+17 -0)
➕ hscontrol/db/oidc_session.go (+102 -0)
➕ hscontrol/db/oidc_session_test.go (+305 -0)
📝 hscontrol/db/schema.sql (+21 -0)
📝 hscontrol/oidc.go (+170 -7)
➕ hscontrol/oidc_test.go (+529 -0)
📝 hscontrol/state/state.go (+83 -0)
📝 hscontrol/types/config.go (+15 -0)
➕ hscontrol/types/oidc_session.go (+56 -0)

📄 Description

This issue is a small proof of concept that fixes https://github.com/juanfont/headscale/issues/1531. The implementation may not be complete yet but fulfils our personal needs on refresh_tokens

Features:

  • Support offline_access scope to retrieve refresh token
  • OIDC session persistence in database to maintain authentication state across restarts and for the store of the refresh_token
  • Background token refresh mechanism that automatically renews OAuth2 tokens before expiration. Configurable with check_interval and expiry_threshold.
  • Background invalidation mechanism that automatically removes session from expired nodes after session_invalidation_grace_period

Current Limitations:

  • With the implementation of the invalidation mechanism, this PoC is a bit designed for our own needs. This can be enhanced and be more generalized. This means: We want the user to have no SSO relogins while he is online. If he's offline for a longer period (and falls into session_invalidation_grace_period), we want him to do a reauth to enforce our compliance checks via Azure. Therefore we delete the refresh tokens on the invalidation goroutine. With this, we did not implement the retrieval of an access_token using the refresh_token when the user connects again after the session_invalidation_grace_period has passed.
  • have read the CONTRIBUTING.md file
  • raised a GitHub issue or discussed it on the projects chat beforehand (not myself - refering to https://github.com/juanfont/headscale/issues/1531)
  • added unit tests
  • added integration tests --> Have prepared some locally but didn't manage to get them tested correctly. Would need a bit of guidance here.
  • 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/2704 **Author:** [@mazlumtoprak](https://github.com/mazlumtoprak) **Created:** 7/24/2025 **Status:** 🔄 Open **Base:** `main` ← **Head:** `feature/planetexpress/oidc-refresh-tokens` --- ### 📝 Commits (5) - [`7d3e7a2`](https://github.com/juanfont/headscale/commit/7d3e7a28e230cd70645297cd28db068445909472) Fix `/machine/map` endpoint vulnerability (#2642) - [`fd8bd3f`](https://github.com/juanfont/headscale/commit/fd8bd3f6a642b062e5d2ffb0c19f0627836463d5) implement oauth2 refresh tokens with background refreshing - [`46816c8`](https://github.com/juanfont/headscale/commit/46816c8a1cb62f0953901cd84c42478f0eedbf37) few improvements: clean database table, more cfg, exact db queries by nodeID - [`da57cf4`](https://github.com/juanfont/headscale/commit/da57cf49872f400c8c1617afb178ad52e66bfb09) fix user reference unit test, fmt - [`a0007a7`](https://github.com/juanfont/headscale/commit/a0007a79b4c4510bbffe709137630892de7937d2) rebase and refactor to new state mgmt ### 📊 Changes **14 files changed** (+1442 additions, -16 deletions) <details> <summary>View changed files</summary> 📝 `CHANGELOG.md` (+7 -1) 📝 `config-example.yaml` (+17 -6) 📝 `docs/ref/oidc.md` (+7 -1) 📝 `hscontrol/app.go` (+40 -0) 📝 `hscontrol/db/db.go` (+73 -1) 📝 `hscontrol/db/node.go` (+17 -0) ➕ `hscontrol/db/oidc_session.go` (+102 -0) ➕ `hscontrol/db/oidc_session_test.go` (+305 -0) 📝 `hscontrol/db/schema.sql` (+21 -0) 📝 `hscontrol/oidc.go` (+170 -7) ➕ `hscontrol/oidc_test.go` (+529 -0) 📝 `hscontrol/state/state.go` (+83 -0) 📝 `hscontrol/types/config.go` (+15 -0) ➕ `hscontrol/types/oidc_session.go` (+56 -0) </details> ### 📄 Description This issue is a small proof of concept that fixes https://github.com/juanfont/headscale/issues/1531. The implementation may not be complete yet but fulfils our personal needs on `refresh_tokens` Features: - Support `offline_access` scope to retrieve refresh token - OIDC session persistence in database to maintain authentication state across restarts and for the store of the refresh_token - Background token refresh mechanism that automatically renews OAuth2 tokens before expiration. Configurable with `check_interval` and `expiry_threshold`. - Background invalidation mechanism that automatically removes session from expired nodes after `session_invalidation_grace_period` Current Limitations: - With the implementation of the invalidation mechanism, this PoC is a bit designed for our own needs. This can be enhanced and be more generalized. This means: We want the user to have no SSO relogins while he is online. If he's offline for a longer period (and falls into `session_invalidation_grace_period`), we want him to do a reauth to enforce our compliance checks via Azure. Therefore we delete the refresh tokens on the invalidation goroutine. With this, we did not implement the retrieval of an `access_token` using the `refresh_token` when the user connects again after the `session_invalidation_grace_period` has passed. <!-- 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. --> <!-- Please tick if the following things apply. You… --> - [X] have read the [CONTRIBUTING.md](./CONTRIBUTING.md) file - [X] raised a GitHub issue or discussed it on the projects chat beforehand (not myself - refering to https://github.com/juanfont/headscale/issues/1531) - [X] added unit tests - [ ] added integration tests --> Have prepared some locally but didn't manage to get them tested correctly. Would need a bit of guidance here. - [X] 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 04:19:05 +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#2813
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?