Switching between associated user accounts in an application

[tharindu-b-hewage]

Description:
User account association can be managed using the Association REST APIs in the Identity Server. The server also allows switching between associated accounts using a token obtained via OIDC flow, in a grant type called account_switch.

The latter is done with an API call as mentioned in this pull request description. Once the token is obtained for the associated user, the relying party can now act on behalf of the associated user.

Association APIs and the account_switch grant type can be utilized in a way that an application can have the capability of switching between associated users. This can be done as explained in the following example.

There is an application called pickup-dispatcher which uses WSO2 Identity Server as its authorization server. A user named John logs in to this application. Besides, John has another account in the Identity Server named as Smith, and he has associated both John and Smith user accounts via the Identity Server's user-portal beforehand.

Now he wants to switch to his associated user account Smith in the pickup-dispatcher, but without logging in again.

1. pickup-dispatcher then invoke account association APIs on-behalf of the John to get his associated user accounts, and provide that to the user John.
2. John selects the account Smith.
3. pickup-dispatcher calls the Identity Server to obtain an access token for the account Smith via the account_switch grant type, with the already available active access token for the account John.
4. The server validates and returns an access token which has the user Smith as it's authorized user.

We need to add the above content with the mentioned scenario as a sample, to the location: https://is.docs.wso2.com/en/next/learn/associating-user-accounts/.