Sovrain
  1. Documentation
  2. Identity provider
  3. For developers

How-to guide

End your app's session when people sign out elsewhere

Receive Sovrain's back-channel or front-channel logout, or a SAML LogoutRequest, and end the matching session in your app.

This guide makes your app end a person’s session when their Sovrain session ends somewhere else: they sign out of Sovrain or of another app, or an admin suspends them. Without it, your app’s own session keeps running until it expires. To send people from your app to sign out of Sovrain, see Sign people out from your app.

Sovrain tells your app in one of three ways. Back-channel logout is the only one that also works when the person’s browser is closed or an admin acts; set it up where you can. Why the reach of a sign-out has limits: About sessions and sign-out.

Before you start

  • Ask an admin to leave Enable sign-out for this application on, on the Sign-out tab of your app. It is on by default.
  • For OpenID Connect, keep the sid claim of the ID token with the person’s session in your app. sid identifies the person’s Sovrain session; every app signed in from the same browser session gets the same value.

Receive back-channel logout

  1. Make an endpoint that is reachable from the internet, for example https://wiki.acme.example/logout/backchannel, and ask the admin to enter it as Back-channel logout URI. Sovrain refuses addresses on private or non-routable networks.
  2. Sovrain sends POST with Content-Type: application/x-www-form-urlencoded and the body logout_token=<JWT>.
  3. Check the logout token as you check an ID token: RS256 signature from jwks_uri, iss is the issuer, aud is your client ID, and iat and exp are current (a logout token is valid for 2 minutes). Also check that events contains the key http://schemas.openid.net/event/backchannel-logout, that there is no nonce, and read sid and sub.
  4. End every session in your app that carries this sid.
  5. Answer with any 2xx status within 5 seconds.

Sovrain sends each logout token once. It does not retry, does not follow redirects, and records the result in your app’s activity, which the admin sees on Access & diagnostics. It calls the URI whenever the person’s Sovrain session ends, also when an admin ends it; the full list of triggers is in OpenID Connect › Back-channel logout.

Receive front-channel logout

Front-channel logout runs in the person’s browser, on Sovrain’s sign-out page.

  1. Make a page, for example https://wiki.acme.example/logout/frontchannel, and ask the admin to enter it as Front-channel logout URI. The same rules as for redirect URIs apply.
  2. Sovrain loads it in a hidden frame as …/logout/frontchannel?iss=https%3A%2F%2Facme.sovrain.net&sid=….
  3. Check iss, then end the session in your app that carries this sid. Let Sovrain’s origin frame the page.

The frame loads only when the person signs out through the browser, not when an admin ends a session. Browsers that block third-party cookies may stop your page from seeing its own session in the frame, so front-channel logout is reliable only when your app shares a domain with Sovrain.

If your app uses SAML

  1. Ask the admin to turn on Enable Single Logout for this application on the Sign-out tab and to enter your SP SLO URL and its binding.
  2. When the person signs out of Sovrain, the browser brings a LogoutRequest to your SP SLO URL. End the session it names by its NameID.
  3. Answer with a LogoutResponse whose InResponseTo is the request’s ID, sent to https://acme.sovrain.net/saml/<app slug>/logout. By default Sovrain requires it to be signed.

Sovrain sends LogoutRequest messages only for sign-ins made while Single Logout was on, and only when the person signs out through Sovrain in the browser: not when an admin acts, and not when another SAML app starts the sign-out. SOAP (back-channel) Single Logout is not supported.