Skip to main content

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.
info

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:

TaskSpecificationHow it works
End the session at the OPRP-initiated logoutThe 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 logoutBack-channel logoutThe 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.

CombinationResult
RP-initiated logout onlyThe 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 logoutThe user logs out at RP 1. The nevisAuth session ends, and nevisAuth notifies RP 1 and RP 2.
Logout at nevisAuth and back-channel logoutThe 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 RPAn 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:

SpecificationnevisAuth as OPnevisAuth as RP
RP-initiated logoutAn 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 logoutWhen 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​

ScenarioRole of nevisAuthResult
The user logs out at NevisOPnevisAuth ends the session and sends a logout token to each RP of the session.
An RP logs the user out at NevisOPnevisAuth ends the session through RP-initiated logout and sends a logout token to each RP of the session.
An external OP logs the user outRPnevisAuth receives the logout token and ends the matching local sessions.
An external OP logs the user out, with nevisAuth as a brokerRP and OPnevisAuth 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:

FeatureRole of nevisAuthSupportedHow to enable
Send logout tokens to the RPsOPYesopenid.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 tokensOPYesopenid.bcl.enabled on the AuthorizationServer.
Publish the logout metadata in the discovery documentOPYesendSessionService 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 nevisAuthOPYesThe 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 issuerOPYesThe 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 OPRPYesThe 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 OPRPYes, with a ScriptStateA 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 nevisAuthRP and OPYes, by defaultThe end reason BCL_RECEIVED in triggerReasons. See nevisAuth as identity broker.
OpenID Connect Front-Channel Logout 1.0 and Session Management 1.0OP and RPNoNot 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​

  1. 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 the jti values of received logout tokens to detect replayed tokens. If an AuthorizationServer sets openid.bcl.enabled to true without 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.
  2. 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 received jti values, so that each instance can send the logout tokens and detect replayed logout tokens.
  3. Enable session indexing for the REST services that you configure: ch.nevis.session.oidc.sid and ch.nevis.session.oidc.sub for the end-session service, and ch.nevis.session.rp.oidc.sid and ch.nevis.session.rp.oidc.sub for 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.
  4. 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:

  1. On the AuthorizationServer, enable OpenID Connect (openid.support), set dataSource to nevismeta, and set openid.bcl.enabled to true. OpenID Connect logout is not available with other data sources. For the nevisMeta setup, see Setting up a nevisMeta Instance.
  2. 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 https URI for the Backchannel Logout URI, and make sure that nevisAuth can reach it over the network.
  3. 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.
  4. To publish the end_session_endpoint in the discovery document, set endSessionService or endSessionEndpoint on the discovery service. Behind nevisProxy, set endSessionEndpoint to the URL of the end-session path in nevisProxy. If back-channel logout is enabled, the discovery document also contains backchannel_logout_supported and backchannel_logout_session_supported.

Configuration for nevisAuth as relying party​

  1. Configure one back-channel logout service for each external OP that nevisAuth trusts.
  2. At each external OP, register the URL of the matching service as the back-channel logout URI of nevisAuth.
  3. Optional: to also end the session at the external OP when the user logs out at Nevis, configure a ScriptState in the logout entry 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:

ClaimValue
issThe issuer of the authorization server.
audThe client ID of the RP.
iatThe time when nevisAuth created the logout token.
expThe expiry time of the logout token. By default, the logout token expires 120 seconds after iat.
jtiA unique identifier of the logout token.
eventsThe back-channel logout event http://schemas.openid.net/event/backchannel-logout.
sidThe session ID. Present if Backchannel Logout Session Required is enabled for the client.
subThe 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.

ParameterDescription
id_token_hintAn ID token that nevisAuth issued to the RP. nevisAuth identifies the session with its sid claim.
client_idThe client ID of the RP. If the request contains id_token_hint, the value must match its aud claim.
post_logout_redirect_uriThe URI to which nevisAuth redirects the browser after the logout.
stateA 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.enabled to true on the AuthorizationServer.
  • Configure the <BackChannelLogout> element. nevisAuth does not start if openid.bcl.enabled is true and 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 contains end_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_uri at the external OP. Most OPs reject an unregistered value.
  • The external OP must publish end_session_endpoint in 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 logout entry. 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 LOGOUT is in the default triggerReasons, 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 iss claim matches the configured issuer of the external OP.
  • The aud claim contains the client ID of nevisAuth at the external OP.
  • The exp claim is not in the past, and the iat claim is at most 60 seconds in the future.
  • The events claim contains the back-channel logout event.
  • The logout token contains a sid claim, a sub claim, or both, and no nonce claim.
  • nevisAuth did not receive the jti value 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 atResult
An RP of nevisAuth, through RP-initiated logoutnevisAuth ends the session and sends a logout token to each RP of the session.
nevisAuth, for example through nevisProxy or the session management APInevisAuth 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 logoutnevisAuth 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 logout entry 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.enabled on 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.enabled to true.
  • The AuthorizationServer uses nevismeta as dataSource. 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 iss claim of the logout token.
  • The aud claim 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 events claim with the back-channel logout event, and an exp claim that is not in the past.
  • The clocks of nevisAuth and the external OP are synchronized.