-
-
Notifications
You must be signed in to change notification settings - Fork 1.3k
website/docs: Update docs for single logout #17169
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
base: main
Are you sure you want to change the base?
Conversation
✅ Deploy Preview for authentik-storybook canceled.
|
✅ Deploy Preview for authentik-docs ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
✅ Deploy Preview for authentik-integrations ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
❌ 2 Tests Failed:
View the top 2 failed test(s) by shortest run time
To view more test analytics, go to the Test Analytics Dashboard |
authentik PR Installation instructions Instructions for docker-composeAdd the following block to your AUTHENTIK_IMAGE=ghcr.io/goauthentik/dev-server
AUTHENTIK_TAG=gh-14a82cff24be2c9223b9c3a49e7f9632f3c623da
AUTHENTIK_OUTPOSTS__CONTAINER_IMAGE_BASE=ghcr.io/goauthentik/dev-%(type)s:gh-%(build_hash)s Afterwards, run the upgrade commands from the latest release notes. Instructions for KubernetesAdd the following block to your authentik:
outposts:
container_image_base: ghcr.io/goauthentik/dev-%(type)s:gh-%(build_hash)s
global:
image:
repository: ghcr.io/goauthentik/dev-server
tag: gh-14a82cff24be2c9223b9c3a49e7f9632f3c623da Afterwards, run the upgrade commands from the latest release notes. |
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.
Absolutely awesome docs. Great job!
|
||
Single logout is a security feature that logs a user out of all their applications with active sessions when they log out of authentik. It uses the OAuth2/OpenID Connect front-channel and back-channel logout specifications in combination with SAML's Single Logout specification. | ||
|
||
For example, if a user is concurrently logged into one OIDC provider and two SAML providers, when the user logs out of authentik, they will automatically be logged out of all three applications. Without SLO configured, users with active sessions across multiple providers would need to manually log out of each one individually. |
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.
For example, if a user is concurrently logged into one OIDC provider and two SAML providers, when the user logs out of authentik, they will automatically be logged out of all three applications. Without SLO configured, users with active sessions across multiple providers would need to manually log out of each one individually. | |
For example, if a user is concurrently logged into one OIDC provider and two SAML providers, when the user logs out of authentik, they will automatically be logged out of all three applications. Without SLO configured, users with active sessions across multiple providers would need to manually log out of each provider. |
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.
Without SLO configured, users with active sessions across multiple providers would need to manually log out of each provider one at a time.
How does that feel?
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.
hmmm they are logging out of applications, right? Not providers. Of course logging out of the app then triggers provider log out... But can we just say applications?
Maybe: "Without SLO configured, users with active sessions across multiple providers would need to manually log out of each application with a different provider one at a time."
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.
Maybe change the whole paragraph to talk about applications since it's speaking in the context of the user, not authentik/providers.
For example, if a user is concurrently logged into one OIDC provider and two SAML providers, when the user logs out of authentik, they will automatically be logged out of all three applications. Without SLO configured, users with active sessions across multiple providers would need to manually log out of each one individually. | |
For example, if a user is concurrently logged into an OIDC application and two SAML applications, when the user logs out of authentik, they will automatically be logged out of all three applications. Without SLO configured, users with active sessions across multiple applications would need to manually log out of each one. |
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.
That works for me, with the slight discomfort that one is not logged into a provider... maybe "logged into an app via a SMAL provider"...
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.
Fixed
For example, if a user is concurrently logged into one OIDC provider and two SAML providers, when the user logs out of authentik, they will automatically be logged out of all three applications. Without SLO configured, users with active sessions across multiple providers would need to manually log out of each one individually. | ||
|
||
:::info | ||
Check with your service provider to see if they support SAML Single Logout or OIDC front-channel/back-channel logout. Not all providers support these features. |
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.
Check with your service provider to see if they support SAML Single Logout or OIDC front-channel/back-channel logout. Not all providers support these features. | |
Check with your service provider to see if they support SAML Single Logout or OIDC front-channel/back-channel logout. Not all applications and services support these features. |
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.
Question about the term "service"... do we absolutely have to introduce ithere, or would "provider" suffice? I'm reluctant to muddy the waters.. if we want to say "service" how can we clarify exactly what we mean? @dewi-tik
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.
Not all service providers support these features
- how's that? I do have a similar concern of using applications and services because I stuck with using provider thoughout
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.
Makes sense
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.
done
website/docs/add-secure-apps/flows-stages/stages/single_logout.md
Outdated
Show resolved
Hide resolved
website/docs/add-secure-apps/flows-stages/stages/single_logout.md
Outdated
Show resolved
Hide resolved
website/docs/add-secure-apps/providers/saml/saml_single_logout.md
Outdated
Show resolved
Hide resolved
website/docs/add-secure-apps/providers/saml/saml_single_logout.md
Outdated
Show resolved
Hide resolved
website/docs/add-secure-apps/providers/saml/saml_single_logout.md
Outdated
Show resolved
Hide resolved
website/docs/add-secure-apps/providers/saml/saml_single_logout.md
Outdated
Show resolved
Hide resolved
website/docs/add-secure-apps/providers/saml/saml_single_logout.md
Outdated
Show resolved
Hide resolved
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.
Absolutely awesome docs. Great job and great features to add.
Co-authored-by: Dewi Roberts <[email protected]> Signed-off-by: Connor Peshek <[email protected]>
Co-authored-by: Dewi Roberts <[email protected]> Signed-off-by: Connor Peshek <[email protected]>
Co-authored-by: Dewi Roberts <[email protected]> Signed-off-by: Connor Peshek <[email protected]>
Co-authored-by: Dewi Roberts <[email protected]> Signed-off-by: Connor Peshek <[email protected]>
Co-authored-by: Dewi Roberts <[email protected]> Signed-off-by: Connor Peshek <[email protected]>
Co-authored-by: Dewi Roberts <[email protected]> Signed-off-by: Connor Peshek <[email protected]>
Co-authored-by: Dewi Roberts <[email protected]> Signed-off-by: Connor Peshek <[email protected]>
Co-authored-by: Dewi Roberts <[email protected]> Signed-off-by: Connor Peshek <[email protected]>
Co-authored-by: Dewi Roberts <[email protected]> Signed-off-by: Connor Peshek <[email protected]>
Co-authored-by: Dewi Roberts <[email protected]> Signed-off-by: Connor Peshek <[email protected]>
Co-authored-by: Dewi Roberts <[email protected]> Signed-off-by: Connor Peshek <[email protected]>
Co-authored-by: Dewi Roberts <[email protected]> Signed-off-by: Connor Peshek <[email protected]>
Co-authored-by: Dewi Roberts <[email protected]> Signed-off-by: Connor Peshek <[email protected]>
Co-authored-by: Dewi Roberts <[email protected]> Signed-off-by: Connor Peshek <[email protected]>
Co-authored-by: Dewi Roberts <[email protected]> Signed-off-by: Connor Peshek <[email protected]>
Co-authored-by: Dewi Roberts <[email protected]> Signed-off-by: Connor Peshek <[email protected]>
Co-authored-by: Dewi Roberts <[email protected]> Signed-off-by: Connor Peshek <[email protected]>
|
||
## Logout flow injection | ||
|
||
authentik dynamically injects logout stages into the user logout flow when provider sessions requiring logout are detected: |
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.
@connor can we be more specific about the flow name? Or is it possibly a custom flow that we do not know the name of? We have the "Default Invalidation Flow"...
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.
Also, this statement applies to situations when SLO is not configured, correct?
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.
The stages are kind of made to be "private". They are not configurable or customizable by the user and the user has no option of interacting with them or removing them
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.
Sure, I remember you told me about the multiple private stages.. but I am wondering about the phrase "the user logout flow ". What flow are we talking about here?
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.
user's active logout flow
may be more appropriate. It's just whatever logout flow a user is going though. that could be the default logout flow, a custom logout flow, any flow that logs a user out
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.
User's current logout flow...? either that or your suggestion, thanks
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.
your suggestion sounds great, done
website/docs/add-secure-apps/flows-stages/stages/user_logout.md
Outdated
Show resolved
Hide resolved
Thank you Dewi :) |
website/docs/add-secure-apps/flows-stages/stages/single_logout.md
Outdated
Show resolved
Hide resolved
website/docs/add-secure-apps/flows-stages/stages/single_logout.md
Outdated
Show resolved
Hide resolved
website/docs/add-secure-apps/flows-stages/stages/single_logout.md
Outdated
Show resolved
Hide resolved
website/docs/add-secure-apps/flows-stages/stages/single_logout.md
Outdated
Show resolved
Hide resolved
website/docs/add-secure-apps/flows-stages/stages/single_logout.md
Outdated
Show resolved
Hide resolved
website/docs/add-secure-apps/flows-stages/stages/single_logout.md
Outdated
Show resolved
Hide resolved
|
||
1. Configure the SLS URL (Single Logout Service URL) - the provider's logout endpoint. | ||
2. Select the SLS Binding (Redirect or POST). | ||
3. Choose a Logout Method; front-channel iframe, front-channel native, or back-channel. |
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.
Is Logout Method also the UI label? If Yes, let's bold it.
And same question about "native".. if that is the redirect option, let's call it "native redirect" or some such.
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.
the redirect and post binding both happen within iframe and native, so calling it native redirect isn't as clean as calling it native. native will also handle post requests if desired, so it makes it sound exclusive to handling redirects. I know it's confusing from all the different wordings, but sticking with native is best for sure
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.
ok cool about the rediret/native, but the terms "Logout Method".. is this a UI component? If yes please bold it, if not please lower-case it.
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.
It is, fixed
website/docs/add-secure-apps/flows-stages/stages/single_logout.md
Outdated
Show resolved
Hide resolved
1. Configure the SLS URL (Single Logout Service URL) - the provider's logout endpoint. | ||
2. Select the SLS Binding (Redirect or POST). | ||
3. Choose a Logout Method; front-channel iframe, front-channel native, or back-channel. | ||
4. Optionally, enable `Sign logout request` for additional security. |
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.
If this is a UI label, should be bold....
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.
fixed
website/docs/add-secure-apps/flows-stages/stages/single_logout.md
Outdated
Show resolved
Hide resolved
- **SAML**: Creates `SAMLSession` records containing the `SessionIndex`, `NameID`, and `NameID format` for each successful authentication. | ||
- **OIDC**: Tracks session identifiers (`sid`) and ID tokens required for logout requests. | ||
|
||
These session records are automatically created during authentication and cleaned up after logout or expiration. |
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.
Can we say "deleted" instead of cleaned up?
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.
done
|
||
## Administrative session termination | ||
|
||
Back-channel logout is triggered even when a user session is terminated via administrative actions: |
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.
Always? Just automatically.. ? If yes, maybe reword to something like: "Back-channel logout is always triggered when a user session is terminated via administrative actions:"
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.
done
3. For each logout method with active sessions, the appropriate logout stage is injected: | ||
- **iframe logout stage** - Injected at index 1 (immediately after the logout stage) for front-channel iframe logout. | ||
- **Native logout stage** - Injected at index 2 (after iframe logout, if present) for front-channel native logout. | ||
- **Back-channel logout** - Executed server-side without injecting additional stages. |
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.
But only if SLO is configured, correct?
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.
yeah, only if an application has been configured to have one of these 3 logout methods and has an active session. but you are unable to add a logout method (iframe, native, backchannel) if you dont have SLO configured for a provider. So that is implied here. The wording is from the perspective of the logout method, not the provider
Changing the sentence above this to the following might help clarify that
authentik dynamically injects logout stages into the user's current logout flow when provider sessions configured for Single Logout are detected:
|
||
This approach ensures that single logout happens automatically without requiring explicit flow configuration. | ||
|
||
## Administrative session termination |
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.
This is the same section/content as in the single-_ogout.md
file, right? Does it need to be here as well? It is specifically about back-channel and SLO, correct? I'd suggest that if you want to mention Administrative session termination, then replace this block with a sentence saying what it is, then link to the section in the single_logout.md
file.
If it absolutely needs to be repeated here, we want to use a to pull it in to both places from a single source. I can point you to docs on how to do that or do it in a subsequent PR if you want.
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.
I don't think it has to be in both places. It kind of made sense in either one, so i put it in both. But I think it makes more sense ot just be in slo instead of user_logout
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.
removed
|
||
OAuth2/OpenID logout is a security feature defined in the OpenID Connect specification. It allows an OpenID Provider (OP), such as authentik, to notify Relying Parties (RPs) when a user session ends. This ensures that all associated applications can properly terminate the user's session. | ||
|
||
For more information about single logout across all providers, see the [Single Logout (SLO) Overview](../../flows-stages/stages/single_logout.md). |
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.
This link will have to be updated when you move the SLO docs to be under Providers.
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.
fixed
1. In the Admin interface, navigate to **Applications** > **Providers**. | ||
2. Edit or create an OAuth2 provider. | ||
3. In the **Logout URI** field, enter the endpoint for logout (if supported by your RP). | ||
4. Using the **Logout method** radio, select whether the RP supports **Front-channel logout** or **Back-channel logout** at that URI. |
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.
Is it a toggle? Let's not use the word "radio"...
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.
It isn't a toggle. A toggle is enabled/disabled. This item renders as a radio, which is a multiple choice option select. Explicitly calling it a radio does feel odd though
"Using the logout method options"?
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.
Oh! Sorry, radio buttons! OK, sorry... you can just say:
"4. Select the Logout method to define whether the RP supports Front-channel logout or Back-channel logout at that URI."
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.
that's much better, fixed
website/docs/add-secure-apps/providers/oauth2/fontchannel_and_backchannel_logout.mdx
Outdated
Show resolved
Hide resolved
website/docs/add-secure-apps/providers/oauth2/fontchannel_and_backchannel_logout.mdx
Outdated
Show resolved
Hide resolved
|
||
### Logout URI format | ||
|
||
The logout URI should be a single URL provided by your Relying Party application, for example: |
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.
If "Logout URI" is a UI component, let's bold it and match capitaliztion of UI.
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.
fixed
Co-authored-by: Tana M Berry <[email protected]> Signed-off-by: Connor Peshek <[email protected]>
Co-authored-by: Tana M Berry <[email protected]> Signed-off-by: Connor Peshek <[email protected]>
Co-authored-by: Tana M Berry <[email protected]> Signed-off-by: Connor Peshek <[email protected]>
…backchannel_logout.mdx Co-authored-by: Tana M Berry <[email protected]> Signed-off-by: Connor Peshek <[email protected]>
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.
Thanks for this awesome documentation to go with your awesome feature, @PeshekDotDev !
I've finished reviewing, so after those and the other editors changes are in LGTM!
|
||
### Front-channel logout | ||
|
||
With front-channel logout, authentik injects an iframe logout stage into the logout flow. This stage loads the Relying Party's front-channel logout URL in a hidden iframe within the user's browser. The logout URL includes session information as query parameters: |
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.
With front-channel logout, authentik injects an iframe logout stage into the logout flow. This stage loads the Relying Party's front-channel logout URL in a hidden iframe within the user's browser. The logout URL includes session information as query parameters: | |
With front-channel logout, authentik injects an iframe logout stage into the logout flow. This stage loads the RP's (relying party) front-channel logout URL in a hidden iframe within the user's browser. The logout URL includes session information as query parameters: |
Details
Docs update for single logout
Checklist
ak test authentik/
)make lint-fix
)If an API change has been made
make gen-build
)If changes to the frontend have been made
make web
)If applicable
make docs
)