User sign-out

Depending on your situation, sign-out can be a more complicated matter than you first think. Below we describe three scenarios and in some cases also choices that can be made in each scenario.

Single-sign-out

Authway supports single-sign-out, which pretty much handles sign-out the same way as single-sign-on works. When an application triggers a sign-out, Authway will check which applications the user is singed in too, and try to sign the user out from each of the applications. Authway supports single-sign-out for both OpenId Connect (OIDC) and SAML protocols. There are two different ways to notify server-side client applications that the user has signed out and the most commonly supported way is to use a front-channel which works for both OIDC and SAML, but for OIDC we recommend back-channel if possible.

Front-channel sign-out for server-side applications

The front-channel sign-out notification is done via the browser and this the only method supported for SAML sign-out. To use front-channel sign-out, the application should register a single URL that should be invoked by Authway when a user sign-out. A call to this URL will typically be handled in a way that the application deletes the cookie that keeps track of the fact that the user is signed-in. The URL is called from a hidden iframe on the signed out page in Authway.

Please note that Front-channel sign-out is broken when browsers block third party cookies. This is because in most scenarios the application cookie won’t be passed and not deleted in the iframe, since it will be a third party cookie.

There are other drawbacks with front channel. It is restricted to a signed in user’s browser to perform the request for sign-out, which makes it impossible to handle scenarios where a user or an administrator wants to force a sign-out from everywhere (including from other devices). This why we recommend back-channel sign-out if possible.

OIDC Front-Channel Logout 1.0 specification

Back-channel sign-out for server-side applications

The back-channel sign-out notification is done through a server-to-server call, where Authway POST a logout (JWT) token to the registered back-channel URL. This is generally not supported out of the box in OIDC libraries so you’ll have to implement it yourself. It is important that the posted token is correctly validated.

OIDC Back-Channel Logout 1.0 specification

Sign-out for browser-based JavaScript applications

For browser-based applications it is not necessary to make any configuration in Authway, but the application must perform monitoring on the check_session_iframe, which is implemented by libraries that are compliant with the OIDC specification, for example oidc-client JavaScript library.

Only sign-out from the Application (but not from Authway or other applications)

There are valid scenarios where the user only want to sign-out from the current application and not a full single-sign-out. If this is a desired scenario the application shall not invoke the sign-out functionality, through OIDC or SAML, in Authway, but rather just remove the user session in the application (aka delete the sign-in cookie).

One problem with this solution is that when the user chooses to sign-in again it will happen automatically since the session is still alive in Authway. This can be confusing for users as it feels like they were not signed out. To counteract that experience, you can force the user to sign in again (se below), but then single-sign-on is instead lost for the application.

The best solution can sometimes be to let users choose if they should sign-out from the application only or if they want a full single-sign-out from all applications where there account is currently used.

Force new sign-in

Authway has support to force a user to make a new sign-in. This can be configured for the application or it can be triggered by passing parameters from the application. To configure the application to always require a new sign-in the “Users SSO time” should be set to a low value, like 5 seconds. The other alternative is to control from the application if a new sign-in should be required or not. When using the OIDC protocol this is done by passing parameter max-age=0 and for SAML this is done by setting ForceAuthentication.

Sign-out from application and Authway (but no other applications)

Another alternative is to sign-out from the application and Authway, but not registering front-channel or back-channel for any applications. When signing out in Authway all refresh tokens are invalidated which in many scenarios still will result in a situation where users are forced to sign-in again, for example all applications that uses access- and/or refresh-tokens. Applications that only uses Authway for authentication can often handle this without affecting the users.

Sign-out without showing Authway signed out page

Some applications prefer to show their own signed out page after a sign-out instead of Authway signed out page. This is challenging to fulfil while still supporting OIDC and SAML protocols correctly (aka the front-channel sign-out). Authway can be configured (requires setting on the instance done by IRM) for automatic re-direct which will re-direct the user back to the application when front-channel sign-out is done. If the applications that the user is signed in to, does not have any front-channel URLs registered the redirect will be performed without showing Authway signed out page.

Subsections of User sign-out

Trigger OpenId Connect Sign-out

An application (relying party) that want to initiate a single-sign-out will do that through the library used for OIDC. If the library doesn’t support sign-out this is possible to trigger from the application anyway by making a re-direct (HTTP GET) to a URL that will be something like this:

GET https://instance.irmciam.se/connect/endsession?
post_logout_redirect_uri={URL TO RETURN USER TO AFTER SIGN OUT}&id_token_hint={ID_TOKEN]&
state={OPTIONAL STATE RETURNED TO CLIENT}
Parameter Requirement Description
post_logout_redirect_uri Recommended The URL where the user will be re-directed after a completing the sign-out. If parameter isn’t supplied a generic signed out message is displayed. The URL must be registered in application configuration for the application in Authway. If an exact match isn’t found the parameter will be ignored and the user will not be redirected back to the application in any way.
id_token_hint Recommended Indication of the user that should be signed out. This is required for post_logout_redirect_uri to be considered. If it isn’t supplied the user might be prompted to sign-out (for security reasons).
state Optional State information that is returned to the client when the user is re-directed after the sign-out. For example you can store information about current user session or a re-direct URL that the user should be returned to within the application after being returned to the post_logout_redirect_uri.

Full specification: OpenID Connect RP-Initiated Logout 1.0

C# example

In this example the application saves information about re-directing the user to Index action after a complete sign-out. We recommend that the local re-direct URL allows anonymous access, or otherwise a new sign-in will be triggered as a result of the sign-out and that will be a strange user experience.

public async Task SignOut()
{
    await HttpContext.SignOutAsync();

    string returnUrl = Url.Action(nameof(Index));
    await HttpContext.SignOutAsync(OpenIdConnectDefaults.AuthenticationScheme,
                new AuthenticationProperties { RedirectUri = returnUrl });
}

Handle OIDC back-channel notification

The URL registered in Authway for back-channel notification when a user signs out will receive an HTTP POST with a logout token (JWT). This JWT token must be correctly validated by checking at least these requirements:

  1. The token is signed by the keys published by Authway (can be found through metadata).
  2. The issuer should be the Authway instance (exact value for issuer is also available in metadata).
  3. The audience should be the client id of the application receiving the notification.
  4. A sub claim that uniquely identifies the user should be present.
  5. A sid claim should be present if the application settings is to include session index.
  6. A nonce claim should be present.
  7. A events claim should be present and it should contain a http://schemas.openid.net/event/backchannel-logout event.

By using the sub claim and optionally the sid the application should invalidate the user session. How this is done will differ depending on platform/application.

.NET Sample

A sample for .NET can be found here.