Choose Account Authentication Action

This tutorial describes an example implementation of an authentication action that allows the user to easily switch accounts that they previously logged in with. The action displays the user all the active Single-Sign On (SSO) sessions that they currently have in the Curity Identity Server and lets them choose one. The user also has an option to log in with another account, not previously used in the current browser or device.

Usually, one user holds one identity (account) with a given service. Very often the user logs in to that account from a private device. However, this is not always the case. Sometimes a service is used from shared computers, where multiple users can access it. There are services where users can hold multiple accounts and need to switch between them. When a user logs in using SSO it gives them a better experience, as they don't have to re-authenticate too often, but it can be a nuisance when the account needs to be often switched. In these situations the user needs to log out, then log in again with the other account. This is where the choose-account authentication action can help.

Installing the Plugin

To install the plugin, clone the GitHub repository, then run mvn package to build the target jar. Copy the jar from the target directory to $IDSVR_HOME/usr/share/plugins/accountchooser on every node of the Curity Identity Server, then restart the server. The plugin is now ready to be configured and used.

Configuring the Plugin

As this is an authentication action plugin, it must be attached to an authenticator. First, the authenticator will be called, then the action will be applied on the authentication result. The plugin can be attached to any authenticator, but it is recommended to use the anonymous authenticator – an authenticator that assigns the user a random subject and automatically passes the authentication. To the user, this will look as if the action kicked in straight away.

If you decide to use a different authenticator, one that assigns an actual identity, then you will have to make some changes in this plugin. You will have to ensure that the identity from the SSO session chosen with this plugin corresponds to the identity obtained with the authenticator. How you do it will depend on how you match the identities and may involve some techniques used in the Account Linking Recipes article.

To start using the plugin, first create the anonymous authenticator, then create the choose-account action and assign it to both the login and SSO flows of the anonymous authenticator.

The only configuration the plugin needs is a list of authenticator ACRs. These are the authenticators that will be used to choose an already authenticated account — the user will be shown only active sessions created with one of these authenticators. The list of these authenticators is also presented to the user so that they can log in with a different account or when the user doesn't have any active SSO session.

Note on the Resulting Claims

The anonymous authenticator used with this action creates a random user's subject — a UUID (or assigns a static subject, depending on the configuration used). This action replaces that random subject with a subject obtained from the chosen SSO session. This means that the subject from the chosen SSO session will be present in the sub claim and the random subject from the anonymous authenticator will be lost (as it is redundant anyway). The subject in the SSO session is the subject obtained from the authenticator's authentication flow and may be a value transformed by actions assigned to that authenticator.

If the action is used in an OIDC flow, the resulting ID token will contain the acr claim with the ACR value of the anonymous authenticator. It is thus recommended to use a meaningful name for the authenticator (e.g., account-chooser), or manually override the ACR value for a meaningful one, e.g., urn:com:example:authentication:account-chooser. To change the default ACR using the admin UI, go to your authentication profile then Authenticators. Edit the anonymous authenticator and switch to the More tab.

Reusing the Same Authenticator

In the Curity Identity Server one authenticator can have one active SSO session. This means that in order to switch accounts the users need to be logged in with different authenticators. If you want to allow numerous users to be logged in simultaneously with the same authenticator, then you will have to create copies of the authenticator and make sure to have a different ACR value on each. The number of instances of the authenticator should match the number of distinct users you want to allow to log in at any one time.

If you decide to use the account chooser action with copies of an authenticator, for the best user experience you should make some updates to the code. The list of available authenticators should in this case display only one authenticator from the duplicated ones, preferably one that doesn't have an active SSO session yet (so that other users are not kicked out). This will require adding some code that will be able to identify the cloned authenticators (e.g., a configuration entry or filtering through an ACR prefix, etc.). The code will then have to choose only the one authenticator that doesn't have an active session, or decide which authenticator to reuse if all would have an SSO session.

For example, the code that maps ACRs into the view data (from the AccountChooserRequestHandler class), could look something along these lines (note that this is not a complete solution):

var htmlAuthenticatorIncludedInList = false

val authenticators = (activeSessionsACRs.value as List<Map<String, String>>).map {
    val acr = it["acr"]!!
    val authenticator = authenticatorDescriptorFactory.getAuthenticatorDescriptors(acr).first

    val isHTMLFormAuthenticator = acr.startsWith("urn:com:example:authenticator:html-form:")

    // Decide whether the authenticator should be listed at the end of the account chooser.
    val includeInAuthenticatorsList = acr.shouldBeIncludedInAuthenticatorsList(isHTMLFormAuthenticator, htmlAuthenticatorIncludedInList)

    return@map AuthenticatorForView(
        acr,
        authenticator.description,
        authenticator.type,
        includeInAuthenticatorsList,
        it["subject"]
    )
}

response.putViewData("authenticators", authenticators, Response.ResponseModelScope.ANY)

Rich Authentication Flows

Using the account chooser action does not limit any features offered by the Curity Identity Server. Every authenticator listed in the action can in itself contain a rich authentication flow, with its own actions, e.g., multi-factor authentication. Once an SSO session is established as a result of running the authentication flow, the account-chooser action is able to make use of that session.

Conclusion

The account-chooser authentication plugin allows the user to have more control over the SSO sessions established with the Curity Identity Server. It will prove helpful in services where a user has multiple accounts and needs to frequently switch between them, or in services that are frequently used on shared devices. Remember, that the presented plugin is a demo implementation of the account chooser, and there are some features that you might have to add yourself to tailor it to your concrete requirements.