-
Notifications
You must be signed in to change notification settings - Fork 8
[docs] feat(url-access-token): write documentation for url access token process (#5544) #294
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.
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
Open
gabriel-peze
wants to merge
2
commits into
main
Choose a base branch
from
issue/5544
base: main
Could not load branches
Branch not found: {{ refName }}
Loading
Could not load tags
Nothing to show
Loading
Are you sure you want to change the base?
Some commits from the old base branch may be removed from the timeline,
and old review comments may become outdated.
Open
Changes from all commits
Commits
File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
42 changes: 42 additions & 0 deletions
42
docs/deployment/breaking-changes/2.5.0-url-access-token-enforcement.md
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,42 @@ | ||
| # URL access token enforcement for email links | ||
|
|
||
| !!! info "" | ||
|
|
||
| * **Introduced in**: `OpenAEV 2.5.0` | ||
|
|
||
| ## Description of changes | ||
|
|
||
| Starting with **OpenAEV 2.5.0**, OpenAEV no longer accepts legacy email URLs that rely on `userId` and `user` query parameters for player access flows. | ||
|
|
||
| OpenAEV now requires a short-lived URL access token through: | ||
|
|
||
| ```text | ||
| /api/url/access?token=<raw-token> | ||
| ``` | ||
|
|
||
| After the first successful access, OpenAEV sets a secure cookie and redirects the user to the target resource URL. | ||
|
|
||
| ## Impact | ||
|
|
||
| Legacy links generated before this change are not compatible with OpenAEV 2.5.0. | ||
|
|
||
| Typical effects of enhanced security include: | ||
|
|
||
| - `401 Unauthorized` when opening old email links | ||
| - Access failures on player routes that previously relied on legacy query parameters | ||
|
|
||
| ## Migration guide | ||
|
|
||
| 1. Upgrade OpenAEV to a version that supports URL access token links. | ||
| 2. Regenerate and resend player emails (Media Pressure, Challenge, and Lessons Learned) so users receive token-based links. | ||
|
|
||
| !!! warning | ||
| Do not keep old links in operational runbooks. Ask users to open newly generated emails after upgrade. | ||
|
|
||
| ## Validation checklist after upgrade | ||
|
|
||
| 1. Send a new player email and confirm the URL format is `/api/url/access?token=...`. | ||
| 2. Open the link and verify the redirect succeeds. | ||
| 3. Confirm the platform sets a secure cookie (`HttpOnly`, `Secure`, `SameSite=Strict`). | ||
|
|
||
|
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,58 @@ | ||
| # URL access token | ||
|
|
||
| This page explains how OpenAEV secures player email links with short-lived URL access tokens. | ||
|
|
||
| ## What is this? | ||
|
|
||
| OpenAEV uses URL access tokens to protect links sent in player-facing emails. | ||
|
|
||
| Instead of exposing persistent identifiers in query parameters, OpenAEV now generates an opaque token and sends links in this format: | ||
|
|
||
| ```text | ||
| /api/url/access?token=<raw-token> | ||
| ``` | ||
|
|
||
| When a player opens the link, OpenAEV validates the token, sets a secure cookie, and redirects to the target page. | ||
|
|
||
| ## Why use it? | ||
|
|
||
| This mechanism reduces the risk of data leakage in browser history, logs, and referrer headers. | ||
|
|
||
| Main security benefits: | ||
|
|
||
| - Token is short-lived and revocable. | ||
| - Token is scoped to a user and an exercise. | ||
| - OpenAEV stores only a SHA-256 hash in the database. | ||
| - OpenAEV removes the token from the URL after first access. | ||
|
|
||
| !!! tip | ||
| This change hardens security without changing the player experience. | ||
|
|
||
| ## How do I do it? | ||
|
|
||
| ### Enable and configure token behavior | ||
|
|
||
| 1. Set the token validity margin after the exercise end date. | ||
| 2. Set the retention window for purge operations. | ||
|
|
||
| | Parameter | Environment variable | Default value | Description | | ||
| |:--|:--|:--|:--| | ||
| | `openaev.url.access.token.expiry-margin-days` | `OPENAEV_URL_ACCESS_TOKEN_EXPIRY-MARGIN-DAYS` | `7` | Adds a grace period after `exercise.end_date` to compute token expiration. | | ||
| | `openaev.url.access.token.retention-days` | `OPENAEV_URL_ACCESS_TOKEN_RETENTION-DAYS` | `30` | Keeps revoked or expired tokens for audit before purge. | | ||
|
|
||
| ### Verify email link flow | ||
|
|
||
| 1. Send a Media Pressure, Challenge, or Lessons Learned email. | ||
| 2. Confirm the email contains `/api/url/access?token=...`. | ||
| 3. Open the link and verify OpenAEV returns a redirect to the target page. | ||
| 4. Verify the browser receives a cookie with `HttpOnly`, `Secure`, and `SameSite=Strict`. | ||
|
|
||
| ## Example | ||
|
|
||
| A player receives this link: | ||
|
|
||
| ```text | ||
| https://<openaev-base-url>/api/url/access?token=<opaque-token> | ||
| ``` | ||
|
|
||
| OpenAEV validates the token and redirects the player to the initial exercise resource. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Let's wait for a release for getting the correct version number