Skip to content

docs(v2): document OIDC single logout (SLO) support #415

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

Merged
kodiakhq merged 2 commits into from
Jul 23, 2026
+110 −14
Merged

docs(v2): document OIDC single logout (SLO) support #415

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
1efa063
docs(v2): document OIDC single logout (SLO) support
erka Jul 23, 2026
069ebc8
Merge branch 'main' into docs/oidc-slo-logout
markphelps Jul 23, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
96 changes: 95 additions & 1 deletion docs/v2/configuration/authentication.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -279,7 +279,7 @@ authentication:
oidc:
enabled: true
email_matches:
- ^.*@flipt.io$
- ^.*@flipt\.io$
providers:
some_provider: # insert your provider name
issuer_url: "https://some.oidc.issuer.com"
Expand Down Expand Up @@ -433,6 +433,100 @@ authentication:

If not specified, the default is an empty map.

#### Single Logout (SLO)

Single Logout (SLO) allows you to terminate a user's session across Flipt and the OIDC provider simultaneously. When a user logs out from one service, the session is invalidated everywhere. Flipt supports both back-channel and front-channel logout as defined by the [OIDC Front-Channel Logout](https://openid.net/specs/openid-connect-frontchannel-1_0.html) and [OIDC Back-Channel Logout](https://openid.net/specs/openid-connect-backchannel-1_0.html) specifications.

##### Back-Channel Logout

Back-channel logout is the most common approach. The OIDC provider sends a signed `logout_token` to Flipt via a server-to-server POST request at `/auth/v1/method/oidc/{provider}/revoke`. Flipt verifies the token and removes the matching session.

No additional configuration is required to enable back-channel logout — it is available whenever an OIDC provider is configured.

To use back-channel logout, register the Flipt revoke endpoint as the provider's **Back-Channel Logout URL**:

```text
https://your.flipt.instance.url.com/auth/v1/method/oidc/{provider}/revoke
```

When the provider initiates a logout, it sends a form-encoded POST request with a `logout_token` parameter. Flipt verifies the token's signature, issuer, and audience, then uses the `sid` (session ID) or `sub` (subject) claim to locate and delete the corresponding authentication record.

##### Front-Channel Logout

Front-channel logout uses browser redirects instead of server-to-server calls. When the OIDC provider initiates logout, it embeds an invisible iframe pointing to Flipt's front-channel logout endpoint. The browser makes a GET request to:

```text
https://your.flipt.instance.url.com/auth/v1/method/oidc/{provider}/revoke?iss={issuer}&sid={session_id}
```

To enable front-channel logout, set `allow_front_channel_logout` to `true` on the provider:

```yaml config.yaml
authentication:
required: true
session:
domain: "flipt.yourorg.com"
secure: true
methods:
oidc:
enabled: true
providers:
some_provider:
issuer_url: "https://some.oidc.issuer.com"
client_id: "some_client_identifier"
client_secret: "some_client_secret_credential"
redirect_address: "https://your.flipt.instance.url.com"
allow_front_channel_logout: true
```

<Warning>
Front-channel logout requires `session.secure: true`. The logout flow sets
`SameSite=None` on session cookies so the browser can discard them in a
cross-origin iframe context. Browsers reject `SameSite=None` cookies unless
the `Secure` flag is set, so enabling front-channel logout without a secure
session will result in a configuration error.
</Warning>

To use front-channel logout, register the Flipt revoke endpoint as the provider's **Front-Channel Logout URL**:

```text
https://your.flipt.instance.url.com/auth/v1/method/oidc/{provider}/revoke
```

The provider includes `iss` and `sid` query parameters so Flipt can identify the session to terminate.

##### End-Session Endpoint

Flipt can also redirect users to the OIDC provider's end-session endpoint when they log out from the UI. This ensures the provider terminates its own session as well.

To enable this, set `use_end_session_endpoint` to `true` on the provider:

```yaml config.yaml
authentication:
required: true
methods:
oidc:
enabled: true
providers:
some_provider:
issuer_url: "https://some.oidc.issuer.com"
client_id: "some_client_identifier"
client_secret: "some_client_secret_credential"
redirect_address: "https://your.flipt.instance.url.com"
use_end_session_endpoint: true
```

When enabled, Flipt constructs a redirect URL using the provider's `end_session_endpoint` (discovered from the OIDC well-known configuration) with the following query parameters:

- `id_token_hint` — the user's ID token
- `post_logout_redirect_uri` — the provider's configured `redirect_address`

<Note>
The `use_end_session_endpoint` option requires the provider to expose an
`end_session_endpoint` in its OIDC discovery document. If the provider does
not, Flipt logs an error and skips the redirect.
</Note>

#### Self-Signed Certificates

If your OIDC provider uses self-signed or internal CA certificates (common with self-hosted Keycloak, Dex, or corporate identity providers), Flipt will reject the TLS connection with an error like:
Expand Down
28 changes: 15 additions & 13 deletions docs/v2/configuration/overview.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -341,19 +341,21 @@ Authentication configuration controls how users and systems authenticate with Fl

#### Authentication Methods: OIDC

| Property | Description | Default | Since |
| ---------------------------------------------------------------------- | ---------------------------------------------------------------- | --------- | ------- |
| authentication.methods.oidc.enabled | Enable OIDC authentication | false | v2.0.0 |
| authentication.methods.oidc.providers.[provider].issuer_url | Provider specific OIDC issuer URL (see your providers docs) | | v2.0.0 |
| authentication.methods.oidc.providers.[provider].client_id | Provider specific OIDC client ID (see your providers docs) | | v2.0.0 |
| authentication.methods.oidc.providers.[provider].client_secret | Provider specific OIDC client secret (see your providers docs) | | v2.0.0 |
| authentication.methods.oidc.providers.[provider].redirect_address | Public URL on which this Flipt instance is reachable | | v2.0.0 |
| authentication.methods.oidc.providers.[provider].scopes | Scopes to request from the provider | | v2.0.0 |
| authentication.methods.oidc.providers.[provider].use_pkce | Enable PKCE with a cryptographic nonce for OIDC authentication | false | v2.0.0 |
| authentication.methods.oidc.providers.[provider].algorithms | List of accepted ID token signing algorithms | ["RS256"] | v2.6.0 |
| authentication.methods.oidc.providers.[provider].fetch_extra_user_info | Fetch additional claims from the provider's UserInfo endpoint | false | v2.6.0 |
| authentication.methods.oidc.providers.[provider].authorize_parameters | Extra query parameters to append to the provider authorize URL | {} | v2.11.0 |
| authentication.methods.oidc.email_matches | List of email addresses (regex) of users allowed to authenticate | | v2.0.0 |
| Property | Description | Default | Since |
| --------------------------------------------------------------------------- | ---------------------------------------------------------------- | --------- | ------- |
| authentication.methods.oidc.enabled | Enable OIDC authentication | false | v2.0.0 |
| authentication.methods.oidc.providers.[provider].issuer_url | Provider specific OIDC issuer URL (see your providers docs) | | v2.0.0 |
| authentication.methods.oidc.providers.[provider].client_id | Provider specific OIDC client ID (see your providers docs) | | v2.0.0 |
| authentication.methods.oidc.providers.[provider].client_secret | Provider specific OIDC client secret (see your providers docs) | | v2.0.0 |
| authentication.methods.oidc.providers.[provider].redirect_address | Public URL on which this Flipt instance is reachable | | v2.0.0 |
| authentication.methods.oidc.providers.[provider].scopes | Scopes to request from the provider | | v2.0.0 |
| authentication.methods.oidc.providers.[provider].use_pkce | Enable PKCE with a cryptographic nonce for OIDC authentication | false | v2.0.0 |
| authentication.methods.oidc.providers.[provider].algorithms | List of accepted ID token signing algorithms | ["RS256"] | v2.6.0 |
| authentication.methods.oidc.providers.[provider].fetch_extra_user_info | Fetch additional claims from the provider's UserInfo endpoint | false | v2.6.0 |
| authentication.methods.oidc.providers.[provider].authorize_parameters | Extra query parameters to append to the provider authorize URL | {} | v2.11.0 |
| authentication.methods.oidc.providers.[provider].use_end_session_endpoint | Redirect to the provider's end-session endpoint on logout | false | v2.11.0 |
| authentication.methods.oidc.providers.[provider].allow_front_channel_logout | Enable OIDC front-channel logout support | false | v2.12.0 |
| authentication.methods.oidc.email_matches | List of email addresses (regex) of users allowed to authenticate | | v2.0.0 |

#### Authentication Methods: GitHub

Expand Down
Loading