OpenID Connect back-channel logout and RP-initiated logout
OpenID Connect logout ends the session of a user at the OpenID Provider (OP) and at the relying parties (RPs) of this session. Nevis supports two OpenID Connect specifications for this. Each specification covers a different part of the logout:
- OpenID Connect Back-Channel Logout 1.0 defines how the RPs learn that the session at the OP ended. The session at the OP ends, for example, when the user logs out at the OP, when an administrator deletes the session, or after an RP-initiated logout. The OP then sends a logout token directly to each RP of the session, without the browser of the user. Each RP ends its own session for this user.
- OpenID Connect RP-Initiated Logout 1.0 defines how the user logs out at an RP and also ends the session at the OP. The RP ends its own session, redirects the browser of the user to the OP, and asks the OP to end the session. This specification does not define how the OP notifies the other RPs. Back-channel logout does this.
OpenID Connect back-channel logout and RP-initiated logout are available as of nevisAuth 9.2611.0 and nevisMeta 9.2611.0. If you upgrade from an earlier version, see Migrating to nevisAuth 9.2611.
How OpenID Connect logout works
Sessions and tokens after a login
After a user logs in to an RP through OpenID Connect, three independent things exist:
- The session of the user at the OP. In Nevis, this is the nevisAuth session. It provides single sign-on to all RPs.
- The application session of each RP. Each RP creates its own session after the login.
- The tokens that the OP issued to each RP: an ID token, an access token, and in some cases a refresh token.
These do not end together on their own. If one of them ends, the others continue to exist. The two specifications connect them, so that a logout at one place also takes effect at the others.
Ending the OP session and notifying the RPs
A complete logout consists of two tasks. Each specification handles one of them:
| Task | Specification | How it works |
|---|---|---|
| End the session at the OP | RP-initiated logout | The RP redirects the browser of the user to the end-session endpoint of the OP. The OP ends its session. |
| Notify the RPs about the logout | Back-channel logout | The OP sends a logout token directly to each RP, server to server. Each RP ends its own application session. |
Consider the following points:
- RP-initiated logout describes who starts the logout: the RP. The browser of the user always goes to the OP. The OP does not call the RP during RP-initiated logout.
- Back-channel logout starts because the OP session ends, not because of RP-initiated logout. Other events that end the session, for example a logout through nevisProxy or the deletion of the session by an administrator, also start back-channel logout. For the events, see Events that trigger back-channel logout.
- An RP that receives a logout token only ends its own application session. It does not end the session at the OP. If the RP is also the OP of other RPs, as nevisAuth is as identity broker, ending its session can in turn notify these RPs. See nevisAuth as identity broker.
How the specifications combine
The following table shows how the specifications combine. In the examples, the user logged in to RP 1 and RP 2 through the same nevisAuth session.
| Combination | Result |
|---|---|
| RP-initiated logout only | The user logs out at RP 1. The nevisAuth session ends. RP 2 is not notified, for example because it has no back-channel logout endpoint, and keeps its session until it ends in another way. For requests with an ID token hint, set openid.bcl.enabled anyway. See RP-initiated logout without back-channel logout. |
| RP-initiated logout and back-channel logout | The user logs out at RP 1. The nevisAuth session ends, and nevisAuth notifies RP 1 and RP 2. |
| Logout at nevisAuth and back-channel logout | The user logs out through nevisProxy, or an administrator deletes the session. nevisAuth notifies RP 1 and RP 2. |
| Back-channel logout received by nevisAuth as RP | An external OP notifies nevisAuth. nevisAuth ends the matching local sessions. As identity broker, nevisAuth also notifies its own RPs. |
OpenID Provider or relying party: the role of nevisAuth
Both specifications have two ends: the OP and the RP. nevisAuth can be at either end. A simple way to tell the roles apart:
- As OP, nevisAuth holds the single sign-on session. Applications log in at nevisAuth, and they log out at nevisAuth.
- As RP, nevisAuth is itself an application of another OP, for example Microsoft Entra ID. nevisAuth logs in at the external OP, and it logs out at the external OP.
The same specification therefore means different things, depending on the role of nevisAuth:
| Specification | nevisAuth as OP | nevisAuth as RP |
|---|---|---|
| RP-initiated logout | An RP of nevisAuth sends the browser to the end-session endpoint of nevisAuth. nevisAuth ends its session. | The user logs out at Nevis. nevisAuth ends its session and sends the browser to the end-session endpoint of the external OP. The external OP ends its session. |
| Back-channel logout | When the nevisAuth session ends, nevisAuth sends a logout token to each RP of the session. | The external OP sends a logout token to nevisAuth. nevisAuth ends the matching local sessions. |
In both roles, RP-initiated logout always goes in the direction of the OP, through the browser. Back-channel logout always goes in the direction of the RPs, server to server. As identity broker, nevisAuth has both roles in the same session.
Supported OpenID Connect logout scenarios
| Scenario | Role of nevisAuth | Result |
|---|---|---|
| The user logs out at Nevis | OP | nevisAuth ends the session and sends a logout token to each RP of the session. |
| An RP logs the user out at Nevis | OP | nevisAuth ends the session through RP-initiated logout and sends a logout token to each RP of the session. |
| An external OP logs the user out | RP | nevisAuth receives the logout token and ends the matching local sessions. |
| An external OP logs the user out, with nevisAuth as a broker | RP and OP | nevisAuth ends the matching local sessions and sends a logout token to each RP of these sessions. |
In the last scenario, nevisAuth is an identity broker: nevisAuth is the RP of an external OP, such as Microsoft Entra ID, and the OP of its own RPs. For more information, see nevisAuth as identity broker.
OpenID Connect logout features in Nevis
The following table shows which features Nevis supports, and how you enable them:
| Feature | Role of nevisAuth | Supported | How to enable |
|---|---|---|---|
| Send logout tokens to the RPs | OP | Yes | openid.bcl.enabled on the AuthorizationServer, the <BackChannelLogout> element, and the Backchannel Logout URI of the clients in nevisMeta. See Configuration for nevisAuth as OpenID Provider. |
Add the sid claim to the ID tokens | OP | Yes | openid.bcl.enabled on the AuthorizationServer. |
| Publish the logout metadata in the discovery document | OP | Yes | endSessionService or endSessionEndpoint on the discovery service. With openid.bcl.enabled, the discovery document also contains the back-channel logout metadata. |
| End the session when an RP sends the browser to nevisAuth | OP | Yes | The end-session service with authstates, exposed through nevisProxy. For requests with an ID token hint, also openid.bcl.enabled. See RP-initiated logout with nevisAuth as OpenID Provider. |
| Accept ID token hints of another issuer | OP | Yes | The end-session service with issuer, keystoreref, keyobjectref, and the post-logout redirect URIs of the clients. See ID tokens of another issuer. |
| Receive logout tokens of an external OP | RP | Yes | The back-channel logout service, the <BackChannelLogout> element, and session indexing. See Configuration for nevisAuth as relying party. |
| Send the browser to the end-session endpoint of an external OP | RP | Yes, with a ScriptState | A ScriptState in the logout entry of the domain. See RP-initiated logout with nevisAuth as relying party. |
| Forward a logout of the external OP to the RPs of nevisAuth | RP and OP | Yes, by default | The end reason BCL_RECEIVED in triggerReasons. See nevisAuth as identity broker. |
| OpenID Connect Front-Channel Logout 1.0 and Session Management 1.0 | OP and RP | No | Not available. |
Components involved in OpenID Connect logout
- nevisAuth acts as OP through the AuthorizationServer, and as RP through the RelyingPartyState. nevisAuth also provides the back-channel logout service and the end-session service.
- nevisMeta stores the logout metadata of each client in the Backchannel Logout URI, Backchannel Logout Session Required, and Post-Logout Redirect URIs fields. In nevisMeta, each RP is registered as a client.
- nevisProxy forwards the logout of the user to nevisAuth. For RP-initiated logout, nevisProxy also forwards the request to the end-session endpoint, together with the SecToken of the user.
Configuring OpenID Connect logout
Configuration for both roles
- Add a
<BackChannelLogout>element to the<SessionCoordinator>. See OpenID Connect back-channel logout. Both roles require this element: as OpenID Provider, nevisAuth stores which clients take part in each session; as relying party, nevisAuth stores thejtivalues of received logout tokens to detect replayed tokens. If an AuthorizationServer setsopenid.bcl.enabledtotruewithout a<BackChannelLogout>element, nevisAuth does not start. If the back-channel logout service has no<BackChannelLogout>element, the service rejects all requests. RP-initiated logout alone does not require this element. - Select the store of the
<BackChannelLogout>element. The in-memory store<LocalStore/>loses its data when nevisAuth restarts, and each nevisAuth instance has its own data. Use it only for testing. In production, use the database store<RemoteStore>with a database connection pool. With more than one nevisAuth instance, the instances then share the clients of each session and the receivedjtivalues, so that each instance can send the logout tokens and detect replayed logout tokens. - Enable session indexing for the REST services that you configure:
ch.nevis.session.oidc.sidandch.nevis.session.oidc.subfor the end-session service, andch.nevis.session.rp.oidc.sidandch.nevis.session.rp.oidc.subfor the back-channel logout service. Sending logout tokens as an OpenID Provider does not require session indexing. Session indexing applies only to sessions that start after you enable it. - Enable terminated session polling in nevisProxy. nevisProxy then also ends its session when nevisAuth ends a session through the back-channel logout service, the end-session service, or the session management API.
Configuration for nevisAuth as OpenID Provider
As OpenID Provider, OpenID Connect logout requires the configuration of all three of the following parts:
- nevisAuth: the back-channel logout configuration and the AuthorizationServer.
- nevisMeta as OpenID Connect data source: nevisAuth reads the clients of the AuthorizationServer from nevisMeta.
- The client entities in nevisMeta: the logout fields of each client tell nevisAuth where to send the logout tokens. nevisAuth sends no logout token to a client without a Backchannel Logout URI.
Configure them as follows:
- On the AuthorizationServer, enable OpenID Connect (
openid.support), setdataSourcetonevismeta, and setopenid.bcl.enabledtotrue. OpenID Connect logout is not available with other data sources. For the nevisMeta setup, see Setting up a nevisMeta Instance. - In nevisMeta, set the logout fields of each client entity: Backchannel Logout URI, Backchannel Logout Session Required, and Post-Logout Redirect URIs. See Entities. Use an
httpsURI for the Backchannel Logout URI, and make sure that nevisAuth can reach it over the network. - For RP-initiated logout, configure the end-session service, and expose it through nevisProxy. Protect the path in nevisProxy with an IdentityCreationFilter of the same realm as the authorization endpoint, so that nevisProxy reuses the existing login of the user, and delegate the SecToken of the user to nevisAuth. nevisAuth identifies the session of the user with this SecToken. Without it, nevisAuth does not end any session.
- To publish the
end_session_endpointin the discovery document, setendSessionServiceorendSessionEndpointon the discovery service. Behind nevisProxy, setendSessionEndpointto the URL of the end-session path in nevisProxy. If back-channel logout is enabled, the discovery document also containsbackchannel_logout_supportedandbackchannel_logout_session_supported.
Configuration for nevisAuth as relying party
- Configure one back-channel logout service for each external OP that nevisAuth trusts.
- At each external OP, register the URL of the matching service as the back-channel logout URI of nevisAuth.
- Optional: to also end the session at the external OP when the user logs out at Nevis, configure a ScriptState in the
logoutentry of the domain. See RP-initiated logout with nevisAuth as relying party.
Back-channel logout with nevisAuth as OpenID Provider
Session tracking for back-channel logout
nevisAuth identifies the session with the session ID (sid) claim. If back-channel logout is enabled, nevisAuth adds the sid claim to each ID token that it issues. All RPs of the same session receive the same sid. The sid does not change when an RP refreshes its tokens, so an RP can store the sid of the first ID token.
nevisAuth records each client that receives an ID token in the session. When the session ends, nevisAuth sends a logout token to each recorded client that has a Backchannel Logout URI. nevisAuth skips clients without a Backchannel Logout URI, without an error. The following clients are not recorded, and nevisAuth does not notify them:
- Clients that receive only access tokens, without an ID token, for example in a pure OAuth 2.0 flow.
- Clients that receive an authorization code, but do not exchange it for tokens.
Events that trigger back-channel logout
By default, the following events trigger back-channel logout:
- The user logs out, for example through the logout function of nevisProxy.
- An authentication flow ends the session with a logout, for example during a SAML or WS-Federation single logout.
- An RP ends the session through RP-initiated logout.
- An administrator deletes the session through the session management API of nevisAuth.
- nevisAuth as identity broker receives a logout token from the external OP. See nevisAuth as identity broker.
By default, a session that expires in nevisAuth or in nevisProxy does not trigger back-channel logout. To change this, set the triggerReasons attribute. For all end reasons, see Session end reasons and back-channel logout.
Logout token sent by nevisAuth
The logout token is a signed JSON Web Token (JWT) with the typ header parameter set to logout+jwt. nevisAuth signs the logout token with the signing key of the authorization server, and does not encrypt it. The logout token contains the following claims:
| Claim | Value |
|---|---|
iss | The issuer of the authorization server. |
aud | The client ID of the RP. |
iat | The time when nevisAuth created the logout token. |
exp | The expiry time of the logout token. By default, the logout token expires 120 seconds after iat. |
jti | A unique identifier of the logout token. |
events | The back-channel logout event http://schemas.openid.net/event/backchannel-logout. |
sid | The session ID. Present if Backchannel Logout Session Required is enabled for the client. |
sub | The subject of the user. Present if Backchannel Logout Session Required is disabled for the client. |
Each logout token contains either sid or sub, never both. If the session has no user, nevisAuth sends sid.
nevisAuth sends a separate logout token to each RP, with the client ID of that RP in the aud claim.
Delivery of the logout token
nevisAuth sends the logout token as an HTTP POST request with the form parameter logout_token to the Backchannel Logout URI of the client. nevisAuth sends the logout tokens in the background, so the session ends at once and does not wait for the responses of the RPs. The session stays ended even if the delivery fails. If the same session is logged out again, nevisAuth does not send the logout tokens a second time. With the database store, if nevisAuth cannot reach the database at this moment, it sends the logout tokens anyway. An RP can then receive the same logout twice. RPs should therefore treat a logout token for a session that already ended as successful.
If the delivery fails with a network error or an HTTP 5xx response, or if nevisAuth cannot create or sign the logout token, nevisAuth retries the delivery up to two times. By default, the retries start about 5 and 30 seconds after the first attempt (firstRetryDelay and secondRetryDelay). nevisAuth varies each delay randomly by up to 20 percent, so that many retries do not reach an RP at the same time. For each retry, nevisAuth creates and signs a new logout token, with new jti, iat, and exp values. If an RP detects replayed logout tokens, it must therefore accept a retry as a new logout token. nevisAuth does not retry after other responses, for example HTTP 4xx. The delivery is best effort: if all attempts fail, the RP is not notified. Deliveries that are still pending when nevisAuth stops abruptly are lost.
RP-initiated logout with nevisAuth as OpenID Provider
With RP-initiated logout, an RP redirects the browser of the user to the end-session endpoint of nevisAuth.
RP-initiated logout is only supported if the user authenticated through Nevis, so that the browser has an authenticated nevisAuth session. nevisAuth verifies the identity of the user with this session before it ends the session.
The RPs must send the browser to the end-session path in nevisProxy, not directly to nevisAuth. nevisProxy forwards the request to nevisAuth, together with the SecToken of the user. nevisAuth identifies the session of the user with this SecToken. If the request reaches nevisAuth without a SecToken, nevisAuth does not end any session, even if the user confirms the logout. For the configuration, see Configuration for nevisAuth as OpenID Provider.
If the user has no nevisAuth session anymore, for example because the session expired, there is no session to end, and nevisAuth does not redirect the browser back to the RP. Behind nevisProxy, the request to the end-session path starts a new authentication, so the user sees the login page instead. Therefore, an RP must always end its own session before it redirects the browser to nevisAuth. The user is then logged out of the RP, even if the browser does not return to the RP.
The default URL path of the end-session service in nevisAuth is /nevisauth/oauth/end_session. The endpoint accepts GET and POST requests with the following optional parameters. For all parameters, see OpenID Connect end-session service.
| Parameter | Description |
|---|---|
id_token_hint | An ID token that nevisAuth issued to the RP. nevisAuth identifies the session with its sid claim. |
client_id | The client ID of the RP. If the request contains id_token_hint, the value must match its aud claim. |
post_logout_redirect_uri | The URI to which nevisAuth redirects the browser after the logout. |
state | A value that nevisAuth returns unchanged in the redirect to the post_logout_redirect_uri. |
If the request contains a valid ID token hint for the current session of the user, nevisAuth ends the session at once. If the ID token hint is missing or belongs to a different session, nevisAuth asks the user to confirm the logout. If the ID token hint is invalid, nevisAuth rejects the request.
An ID token hint requires that back-channel logout is enabled on the authorization server. Otherwise, the ID token has no sid claim. See RP-initiated logout without back-channel logout.
nevisAuth redirects the browser only to a post_logout_redirect_uri that exactly matches one of the Post-Logout Redirect URIs of the client in nevisMeta, or, for ID tokens of another issuer, one of the URIs in the configuration of the end-session service. If a request with an ID token hint contains an unregistered URI, nevisAuth rejects the request and does not end the session. If the user confirms the logout on the confirmation page, nevisAuth ends the session also if the URI is not registered, but does not redirect the browser. If the request contains no post_logout_redirect_uri, nevisAuth does not redirect the browser.
When the session ends, nevisAuth sends logout tokens to the RPs of the session, including the RP that started the logout. For more information, see Back-channel logout with nevisAuth as OpenID Provider.
RP-initiated logout without back-channel logout
RP-initiated logout does not need back-channel logout to end the session. However, nevisAuth adds the sid claim to the ID tokens only if openid.bcl.enabled is true on the AuthorizationServer. Without the sid claim, nevisAuth rejects every request that contains an id_token_hint with HTTP 400. nevisAuth does not end the session, and the browser does not return to the RP. Without openid.bcl.enabled, only requests without an ID token hint work, and nevisAuth always asks the user to confirm the logout.
The specification recommends that RPs send id_token_hint, and many RPs always send it. To use RP-initiated logout with these RPs, also when you do not want to send logout tokens, configure the following:
- Set
openid.bcl.enabledtotrueon the AuthorizationServer. - Configure the
<BackChannelLogout>element. nevisAuth does not start ifopenid.bcl.enabledistrueand the element is missing. See Configuration for both roles. - Leave the Backchannel Logout URI of the clients in nevisMeta empty. nevisAuth sends no logout token to a client without a Backchannel Logout URI.
ID tokens that nevisAuth issued before you set openid.bcl.enabled contain no sid claim. nevisAuth rejects requests with these ID tokens as hints, until the RP receives a new ID token, for example when the user logs in again.
ID tokens of another issuer
Usually, an AuthorizationServer of nevisAuth issues the ID tokens that the RPs send as ID token hint. If another component issues the ID tokens, but the session of the user exists in nevisAuth, configure the end-session service without an AuthorizationServer. Set the following values directly on the end-session service:
- The issuer of the ID tokens.
- The certificate that verifies the signature of the ID tokens. To support key rotation, you can also set the certificate of the previous key.
- For each RP, the client ID and the URIs to which nevisAuth may redirect the browser after the logout.
nevisAuth then does not use nevisMeta for RP-initiated logout. The sid claim of the ID tokens must contain the ID of the nevisAuth session of the user, or the value of the session attribute ch.nevis.session.oidc.sid. Otherwise, nevisAuth does not recognize the session of the ID token hint, and asks the user to confirm the logout. For the configuration, see OpenID Connect end-session service.
RP-initiated logout with nevisAuth as relying party
When nevisAuth is the RP of an external OP, the user has two single sign-on sessions: one at nevisAuth and one at the external OP. A logout at Nevis ends the nevisAuth session. With RP-initiated logout as RP, nevisAuth also sends the browser to the end-session endpoint of the external OP, so that the external OP ends its session too.
How RP-initiated logout as relying party works
During the login, the RelyingPartyState stores the following session attributes:
[AuthStateName].upstreamIdToken: the ID token that nevisAuth received from the external OP.[AuthStateName].upstreamEndSessionEndpoint: the end-session endpoint of the external OP. The RelyingPartyState only stores this attribute if the discovery document of the external OP containsend_session_endpoint.
When the user logs out through nevisProxy, nevisAuth runs the AuthState of the logout entry of the domain. For more information on entries, see Authentication processing, AuthStates, and state flow. A ScriptState in this entry reads the two session attributes, and redirects the browser to the end-session endpoint of the external OP. The redirect contains the ID token as id_token_hint, and a post_logout_redirect_uri. nevisAuth ends its own session with the end reason LOGOUT.
Configuring RP-initiated logout as relying party
The following example configures the logout entry of the domain of the RelyingPartyState ExternalOp:
<Domain name="EXTERNAL_OP" default="false">
<Entry method="authenticate" state="ExternalOp"/>
<Entry method="logout" state="ExternalOpLogout"/>
</Domain>
<AuthState name="ExternalOpLogout" class="ch.nevis.esauth.auth.states.scripting.ScriptState" final="true">
<ResultCond name="ok" next="ExternalOpLogout"/>
<Response value="AUTH_DONE"/>
<property name="scriptLanguage" value="groovy"/>
<property name="script" value="file:///var/opt/nevisauth/default/conf/external-op-logout.groovy"/>
</AuthState>
The ScriptState needs the ResultCond ok, because the ScriptState uses this result to continue. As the state is final, the next attribute is not used.
The script external-op-logout.groovy builds the redirect. For the response methods, see Redirect and transfer.
import java.net.URLEncoder
def endSession = session['ExternalOp.upstreamEndSessionEndpoint']
def idToken = session['ExternalOp.upstreamIdToken']
if (!endSession || !idToken) {
LOG.warn('The end-session endpoint or the ID token of the external OP is missing')
response.setResult('error')
return
}
def idTokenHint = URLEncoder.encode(idToken, 'UTF-8')
def postLogoutRedirectUri = URLEncoder.encode('https://www.example.com/logged-out', 'UTF-8')
response.setTransferDestination("${endSession}?id_token_hint=${idTokenHint}&post_logout_redirect_uri=${postLogoutRedirectUri}")
response.setIsRedirectTransfer(true)
response.setResult('ok')
Consider the following points:
- Register the
post_logout_redirect_uriat the external OP. Most OPs reject an unregistered value. - The external OP must publish
end_session_endpointin its discovery document. If the external OP does not support RP-initiated logout, the script cannot redirect, and only the nevisAuth session ends. - Only a logout through nevisProxy runs the
logoutentry. If the nevisAuth session ends in another way, for example through RP-initiated logout of an RP of nevisAuth, the session management API, expiry, or a logout token of the external OP, nevisAuth does not redirect the browser to the external OP. - As the end reason
LOGOUTis in the defaulttriggerReasons, nevisAuth sends logout tokens to its own RPs, if you configured back-channel logout as OP. - If the external OP then sends a logout token to nevisAuth, the session no longer exists. nevisAuth answers with HTTP 200, and nothing else happens.
Back-channel logout with nevisAuth as relying party
With back-channel logout, nevisAuth as RP receives logout tokens from an external OP and ends the matching local sessions. nevisAuth receives the logout tokens on its back-channel logout service, with the default URL path /nevisauth/oauth/backchannel_logout.
nevisAuth accepts a logout token only if all of the following conditions are true:
- The logout token is signed, and the signature is valid. nevisAuth gets the keys from the JSON Web Key Set (JWKS) URI of the external OP.
- The
issclaim matches the configured issuer of the external OP. - The
audclaim contains the client ID of nevisAuth at the external OP. - The
expclaim is not in the past, and theiatclaim is at most 60 seconds in the future. - The
eventsclaim contains the back-channel logout event. - The logout token contains a
sidclaim, asubclaim, or both, and nononceclaim. - nevisAuth did not receive the
jtivalue before. This protects against replayed logout tokens.
nevisAuth stores the received jti values in the store of the <BackChannelLogout> element. For this reason, the <BackChannelLogout> element is also required when nevisAuth acts only as RP.
To find the local sessions, nevisAuth uses the values that it received in the ID token of the external OP at login. If the logout token contains a sid claim, nevisAuth ends the session with this sid. Otherwise, nevisAuth ends all sessions of the user with this sub from this OP. The RelyingPartyState stores these values in the session attributes ch.nevis.session.rp.oidc.sid and ch.nevis.session.rp.oidc.sub.
nevisAuth responds with HTTP 200 to a valid logout token, even if no matching session exists. nevisAuth responds with HTTP 400 to an invalid logout token. If nevisAuth receives a logout token with a jti value that it already received, nevisAuth responds with HTTP 200 if the matching sessions already ended, and with HTTP 400 if a matching session still exists. A rejected logout token does not end any session.
nevisAuth as identity broker
As identity broker, nevisAuth is the RP of an external OP, such as Microsoft Entra ID, and the OP of its own RPs. The user authenticates at the external OP, and nevisAuth creates one session that has both roles. The RPs of nevisAuth log in to this session.
A logout can start at three places. The result depends on where the logout starts:
| The logout starts at | Result |
|---|---|
| An RP of nevisAuth, through RP-initiated logout | nevisAuth ends the session and sends a logout token to each RP of the session. |
| nevisAuth, for example through nevisProxy or the session management API | nevisAuth ends the session and sends a logout token to each RP of the session. For a logout through nevisProxy, nevisAuth can also send the browser to the external OP. See RP-initiated logout with nevisAuth as relying party. |
| The external OP, through back-channel logout | nevisAuth ends the session and sends a logout token to each RP of the session. |
When nevisAuth forwards a logout from the external OP, it sends new logout tokens with the sid of its own session to its own RPs. nevisAuth does not send a logout token back to the external OP, so the logout does not loop between the OPs. nevisAuth sends the logout tokens of a session only once. An exception is a database error during the back-channel logout, see Delivery of the logout token.
To end only the local session when the external OP logs the user out, remove the end reason BCL_RECEIVED from triggerReasons. The RPs of nevisAuth then keep their sessions until the sessions end in another way. For more information, see Session end reasons and back-channel logout.
A logout through nevisProxy can also end the session of the user at the external OP, if you configure RP-initiated logout as RP. See RP-initiated logout with nevisAuth as relying party. Other logouts, for example the RP-initiated logout of an RP of nevisAuth, do not end the session of the user at the external OP.
Planning considerations for OpenID Connect logout
Consider the following points when you plan OpenID Connect logout:
- Each RP that must be notified needs a back-channel logout endpoint, and nevisAuth must be able to reach this endpoint over the network. Check firewalls, proxies, and DNS between nevisAuth and the RPs. An RP without a reachable back-channel logout endpoint keeps its session until the session ends in another way, for example through expiry.
- Back-channel logout ends the session of the RP on the server. A browser tab of the RP that is already open is not updated. The tab still looks logged in until it sends the next request to the RP, or until the user reloads the page. If an RP must update its user interface at once, the RP must check its session itself, for example when the tab gets the focus.
- Back-channel logout is a server-to-server request. Browser settings that block third-party cookies or iframes do not affect it.
- If you upgrade several nevisAuth instances that share a session database, configure OpenID Connect logout only after all instances run nevisAuth 9.2611. Earlier instances do not index the attributes that OpenID Connect logout needs, and do not send logout tokens. See Upgrading nevisAuth instances that share a session database.
- Logout does not invalidate the access tokens that nevisAuth already issued. Native apps, mobile apps, and APIs can still use these access tokens until they expire. Use short lifetimes for access tokens to limit this time.
- By default, a session that expires does not trigger back-channel logout. Configure the session timeouts of the RPs accordingly. To also notify the RPs when a session expires, set
triggerReasons. See Session end reasons and back-channel logout. - An RP that still has a session after the nevisAuth session expired may start an RP-initiated logout for a user without a nevisAuth session. nevisAuth cannot return such a user to the RP. Make sure that the RPs end their own session before they redirect the browser to nevisAuth. See RP-initiated logout with nevisAuth as OpenID Provider.
Limitations of OpenID Connect logout in Nevis
- Access tokens and refresh tokens that nevisAuth issued in the session stay valid until they expire.
- Nevis does not support OpenID Connect Front-Channel Logout 1.0 or OpenID Connect Session Management 1.0.
- As identity broker, nevisAuth only forwards a logout through nevisProxy to the external OP, and only with a ScriptState in the
logoutentry of the domain. Other logouts, for example the RP-initiated logout of an RP of nevisAuth, do not end the session of the user at the external OP. See RP-initiated logout with nevisAuth as relying party. - Back-channel logout notifies only OpenID Connect clients. It does not notify the SAML service providers of the same session.
- As RP, nevisAuth rejects encrypted logout tokens, and accepts only logout tokens signed with RSA keys.
- RP-initiated logout is only supported for users who authenticated through Nevis and have an authenticated nevisAuth session. If the user has no nevisAuth session, nevisAuth does not redirect the browser back to the RP.
- RP-initiated logout with an ID token hint requires
openid.bcl.enabledon the AuthorizationServer, also if you do not use back-channel logout. See RP-initiated logout without back-channel logout. - The logout confirmation page is valid for 10 minutes, and only on the nevisAuth instance that showed it. With several nevisAuth instances, route the confirmation to the same instance. See OpenID Connect end-session service.
Troubleshooting OpenID Connect logout
nevisAuth does not start after you enable back-channel logout
An AuthorizationServer sets openid.bcl.enabled to true, but the <SessionCoordinator> has no <BackChannelLogout> element. Add the <BackChannelLogout> element. Without this element, the back-channel logout service also rejects all requests. See Configuration for both roles.
nevisAuth sends no logout tokens
Check the following points:
- The AuthorizationServer sets
openid.bcl.enabledtotrue. - The AuthorizationServer uses
nevismetaasdataSource. With other data sources, nevisAuth sends no logout tokens. - The client entities in nevisMeta have a Backchannel Logout URI.
- The clients received an ID token in the session. Clients that received only an access token are not notified.
The ID tokens contain no sid claim, or nevisAuth rejects requests with an ID token hint
The AuthorizationServer does not set openid.bcl.enabled to true. Without back-channel logout, nevisAuth adds no sid claim to the ID tokens. The end-session endpoint then rejects requests with an id_token_hint with HTTP 400. Set openid.bcl.enabled to true, also if you only use RP-initiated logout. If the requests still fail, the RP may send an ID token that nevisAuth issued before the change. See RP-initiated logout without back-channel logout.
RP-initiated logout does not end the session
The user confirms the logout, but the session still exists. The request reached nevisAuth without the SecToken of the user, for example because the RP sent the browser directly to nevisAuth. Expose the end-session service through nevisProxy, and make sure that the RPs use the end-session path in nevisProxy. See Configuration for nevisAuth as OpenID Provider.
RP-initiated logout fails with HTTP 400 and the session continues
The post_logout_redirect_uri of the request does not exactly match one of the Post-Logout Redirect URIs of the client in nevisMeta. Register the exact URI in the client entity in nevisMeta. If you configured the end-session service for ID tokens of another issuer, add the exact URI to the client.<clientId>.postLogoutRedirectUris property of the end-session service.
The session ends, but the browser does not return to the RP
The user confirmed the logout on the confirmation page, and the post_logout_redirect_uri of the request does not exactly match one of the registered URIs. nevisAuth ends the session, but does not redirect the browser to an unregistered URI. Register the exact URI as described in the previous section.
After the confirmation, nevisAuth also needs the client_id parameter to check the URI. If the request contains no client_id, nevisAuth does not redirect the browser. Make sure that the RPs always send client_id, also together with id_token_hint.
The logout does not find existing sessions
Session indexing applies only to sessions that start after you enable it. Sessions that already existed are not found until they end. If several nevisAuth instances share a session store, configure the same SessionIndexing attributes on all instances.
An RP does not receive a logout token
Check whether the end reason of the session is in triggerReasons. For example, by default, a session that expires does not trigger back-channel logout. Also check that nevisAuth can reach the Backchannel Logout URI of the client. To find out why nevisAuth did not send a logout token, set the trace group BclSender to DEBUG. See Logging configuration.
nevisAuth rejects the logout tokens of an external OP
To find out why nevisAuth rejects a logout token, set the trace group BclReceiver to DEBUG. Check the following points:
- The configured issuer of the back-channel logout service matches the
issclaim of the logout token. - The
audclaim contains the client ID of nevisAuth at the external OP. - The external OP signs the logout token with an RSA key, and does not encrypt it.
- The logout token contains the
eventsclaim with the back-channel logout event, and anexpclaim that is not in the past. - The clocks of nevisAuth and the external OP are synchronized.