Skip to content
Connect2id

How to implement user account / session switching at an IdP

This guide explains how to support account switching with the Connect2id server:

  • Enable users with multiple identities to maintain parallel IdP sessions in their browser (one session per identity).

  • Enable a client application (OpenID relying party) to request the IdP to switch the user’s identity, for example from a regular user to an administrator.

In the simple case where the user is limited to a single IdP session, a single session cookie is sufficient. For example:

sid: jHO2csdWyQH_I310OLmkxg.Cmw2Q_jmvmCBKetjnE3Sqw

To support parallel IdP sessions in a browser, a different cookie schema is required.

One approach is to store each session identifier in a separate cookie and maintain a registry cookie listing the available browser sessions, together with a pointer cookie indicating the currently active session. Each slot uses a random two-character identifier.

sid-list: k7,p2,x9
sid-k7: m8SSyLBjR1fzZjg9YIR1fw.4uArSMwwT3kLPoeg2NNGkA
sid-p2: ZcussX5VUm0B3gW_I8MoTg.y_ipI6l9lFNlWdpit9m54w
sid-x9: uej0Yfw6VE5KmU0o9fslog.kB4bs__7oAXB-ejjgGuQyQ
current-session: p2

The sid-list cookie enables the login page to determine which session cookies are present without relying on contiguous numeric indices. If a session expires or is closed, its entry can simply be removed from the registry and, if necessary, the current-session pointer updated.

How to request an account switch from a client application

An OpenID relying party can signal that a user wishes to switch to a different identity by making an OpenID authentication request with the optional prompt=select_account parameter:

https://c2id.com/login?
 response_type=code
 &scope=openid%20email
 &client_id=123
 &state=af0ifjsldkj
 &redirect_uri=https%3A%2F%2Fclient.example.org%2Fcb
 &prompt=select_account

If you’re using the OpenID Connect SDK for Java:

new AuthenticationRequest.Builder(
    ResponseType.CODE,
    new Scope("openid", "email"),
    new ClientID("123"),
    URI.create("https://client.example.org/cb"))
    .state(new State("af0ifjsldkj"))
    .prompt(new Prompt(Prompt.Type.SELECT_ACCOUNT))
    .build()
    .toURI();

The prompt parameter is specified in OpenID Connect Core 1.0.

How to handle an account switch request with the Connect2id server

When the Connect2id server receives an OpenID authentication request with prompt=select_account, it returns an auth prompt to the login page with select_account set to true:

{
  "type"           : "auth",
  "sid"            : "g6f5K6Kf6EY11zC00errCf64yLtg9lLANAcnXQk2xUE",
  "display"        : "popup",
  "select_account" : true
}

When an account switch is requested, the IdP should display a screen listing the current browser sessions, along with an option to log in with another identity.

Example:

  • Continue as:
    • Alice (session in sid-k7)
    • Bob (session in sid-p2)
    • Claire (session in sid-x9)
  • Log in as someone else

To render the details of the available user sessions (such as username, email, and profile picture), retrieve the session object for each sid-[n] cookie via the session store API of the Connect2id server:

GET /session-store/rest/v2/sessions HTTP/1.1
Host: c2id.com
Authorization: Bearer ztucZS1ZyFKgh0tUEruUtiSTXhnexmd6
SID: m8SSyLBjR1fzZjg9YIR1fw.4uArSMwwT3kLPoeg2NNGkA

HTTP/1.1 200 OK
Content-Type: application/json

{
  "sub"           : "alice",
  "auth_time"     : 1400491648,
  "creation_time" : 1400491648,
  "max_life"      : 20160,
  "auth_life"     : 10080,
  "max_idle"      : 1440,
  "claims"        : { "email"   : "alice@wonderland.net",
                      "name"    : "Alice Adams",
                      "picture" : "https://www.gravatar.com/avatar/205e460b479e2e5b48aec07710c08d50" }
}

If a sid-[n] has expired, the endpoint returns a 404 Not Found.

If the user selects an existing session, the login page should restart the authZ session, with the prompt=select_account parameter removed from the OpenID request (to avoid triggering the select account prompt again).

If the user chooses to log with a non-listed account, authenticate the user and then continue the original authorisation session as usual.

When switching, ensure the current-session cookie value is updated accordingly.

User-initiated account switching

The IdP may also users to switch their identity on their own initiative, without relying on a prompt=select_account request from a client application. This can be implemented by providing a UI control that opens the account-switching menu described above.

How to end a user session

If users are given the option to end a session, this can be implemented with a delete call to the Connect2id server session store API.

How to start a user session outside a login flow

The IdP can log in a user without an initiating client request by posting a new session to the Connect2id server.

Future improvements

A possible future improvement is to simplify account switching so that more of the required logic can be handled directly by the authorisation session API.

If you have comments, suggestions, or use cases to discuss, let us know.