Switch linked user

In scenarios where linked users are used there can be situation where an application want to trigger a switch to another of the linked users then the one currently using the application.

If the application requests the org scope during sign-in a may_login claim is included in the claims for users that have other linked users. The may_login claim is a JSON object with an array of users that are linked to the current user.

Example of a may_login claim

Here is an example with typical claims in a token for a user that has two linked child users to a parent user.

"sub": "dd41355c-95d9-4bf1-9c21-523b5b40f9f4",
"oid": "e4b8a6ff-cdb1-45f8-b255-8df7a09a9596",
"tid": "567c9683-4603-4279-9e53-ed77b060fe72",
"companyname": "Organisation A",

"may_login": [
    {
        "oid": "dd41355c-95d9-4bf1-9c21-523b5b40f9f4", 
        "tid": "ffffffff-ffff-ffff-ffff-ffffffffffff", 
        "companyname": "Privatpersoner"
    },
    {
        "oid": "4a7b708d-b7d3-4931-b3be-1d86e72214a5", 
        "tid": "1b30a7a4-b271-493a-a315-d35e976f11cf", 
        "companyname": "Organisation B"
    }
]

Explanation of thoose claims:

  • The sub claim will be the same for all users. This is the definition of a linked user.
  • The oid claim will only exist for users that have a different unique identifier in Authway, than the sub claim. It will be emitted for child accounts, but not for the parent.
  • The tid claim identifies the current tenant id and the name of the organisation is in companyname claim.
  • The may_login contains two entries in the array and each entry has claims explained above.
  • The user in tenant “Privatpersoner” is the parent user. This can be concluded because the value of oid is the same as sub claim.
  • There are no information about the users eventual permissions to the application in the may_login claim. If that information is needed it can be requested through the admin APIs.

Trigger a switch to a specific user

To change the current user to one of the other two users that exists in the may_login claim can be done by passing either the tenant or the oid as parameter to the authorize endpoint.

The tenant id for the user is in the tid claim as explained above. So to switch to the user that belongs to “Organisation B” in the example above, the tenant id 1b30a7a4-b271-493a-a315-d35e976f11cf should be passed as explained in “Only allow users from a specific tenant to sign in”.

The other alternative is to pass the oid value as user_id parameter to the authorize endpoint. Here is an example where a typical re-direct to the autorize endpoint is extended with the user_id parameter with the value of oid claim from Organisation B in the example above:

https://YOURINSTANCE.irmciam.se/connect/authorize?
          client_id=YOUR_CLIENT_ID
          &redirect_uri=https%3A%2F%2Fclient.example.org%2Fcallback
          &response_type=code
          &scope=openid
          &state=YOUR_STATE
          &user_id=4a7b708d-b7d3-4931-b3be-1d86e72214a5