How to implement account switching

This guide is for advanced identity providers which want to support account switching:

  • Users with multiple identities can have parallel sessions in their browser with the IdP, one for each identity.

  • Applications (relying parties) can request the IdP to switch the user's identity, for example from regular user to administrator.

Cookie schema

In the simple case, one IdP session per browser, a single cookie is sufficient:

sid: Ahb1Aithae9aich3lee8xai3haex2mei

To support parallel IdP sessions in a single browser a more complex cookie schema is needed.

One way to implement that is to give the session ID for each identity a different cookie name, and set a separate cookie to keep track of the currently active session:

sid-01: eeheemee9aiquie0reizeem9Reeghoh3
sid-02: xaa3eeH8miwaigooThooqu3fooYeogei
sid-03: PhegaiT7ohgei1ee9AemeiziXah7ohge
current-session: sid-02

How can client apps request an account switch

An OpenID relying party (client app) 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 set:

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(
    new 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 and its values are specified in OpenID Connect Core 1.0.

Handling switch account requests with the Connect2id server

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

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

When switch account is signaled, an IdP will typically display a form with choices like those:

  1. Continue as Alice (session in sid-01)
  2. Continue as Bob (session in sid-02)
  3. Continue as Claire (session in sid-03)
  4. Log in as somebody else

To render the above form (with name, email, photo, etc), i.e. the identities that have active sessions, retrieve the session details for each found found 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: eeheemee9aiquie0reizeem9Reeghoh3
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"   : "[email protected]",
                      "name"    : "Alice Adams",
                      "picture" : "https://www.gravatar.com/avatar/205e460b479e2e5b48aec07710c08d50" }
}

If a sid-[n] has expired, you'll get a 404.

If the user chooses to go along with an existing session, let the login page restart the authZ session, but with the prompt=select_account parameter stripped from the OpenID request (so as not to trigger an auth prompt again).

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

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

User-initiated account switching

The IdP can also enable users to switch their current identities on their own initiative, without relying on a client app to trigger that.

Simply provide them with a page where they can view the above account switching menu.

There you can also implement the following options:

  1. Let the user log out a particular identity. To do that simply make a delete call to the session store of the Connect2id server.

  2. Let the user start a new session for another non-listed idenity. Again, the session store API can help with that, by letting an IdP login a user without needing an explicit OpenID authentication request from a relying party.

Future improvements

We would like to simplify the implementation of account switching in a future release of the Connect2id server, so that the login page API can take care of much of what is explicitly required above. If you have comments or suggestions, or wish to discuss a use case, let us know.