07 User Account, Source System User Mapping and Single-Sign-On

OneList maintains it own user accounts which includes the following information:

• UserId - internal use for OneList;
• UserName - a unique key for every user. Its value is based on the customer's main user source;
• Profile - user profile, e.g. first name, last name, email;
• Manager - optional, the user's reporting manager;

Identity the main user source

It is important to identify which system OneList is the customer's main user source. The main user source is the source of truth of user information and is used to propagate users in other systems in the organisation.  Generally, it is the organisation's Identity Provider system (IDP), e.g. active directory, Azure AD, or the ERP system, e.g. SAP. 

OneList creates new user accounts based on the main user source and synchronise user profile with the main user source periodically or on demand. 

Identity how users are linked between OneList and other source systems

The OneList Adapter for each source system is responsible for linking the source system user with OneLIst user account. Generally a user can be automatically linked by his or hers UserName or Email.

When user cannot be automatically linked to OneList user for a source system, the user will need to manually link the accounts via the OneList user setting page before the user can access his or her tasks from that source system.

Where is the user linkage saved and how it is used

The linking between OneList user and external user is saved in the ExternalLogin table in the RoleManager database. The user linking information in this table is used by the RoleManager external log in process and the OneList task generation and task action processes:

• When user logs in via external Idp account, RoleManager uses the Idp's use id to find the RoleManager user id in the ExternalLogin table and grants access to the user;
• When OneList receives a task from Source System, it first uses the source system user id to find the RoleManager user, then finds the OneList user from the RoleManager user, then assigns the task to the OneList user. The reverse lookup process is used to identify the source system user id when user actions a task.

OneList user account creation and Single-Sign-On

There are two scenarios that an OneList user account is created:

1. When a new task assignee is identified in a source system. In this case, the OneList Adapter makes a query to OneList after every task upload, to find if there is any user for that source system requires linking to OneList user account. If OneList returns a list of the source system user id then the OneList Adapter can post the full detail of those uses to OneList. OneList then creates new user account if require and links the source system user id with the OneList user account. The prerequisite of this scenario is that the OneList adapter has full information of the use account including UserName and email.
2. When a user logs on to OneList (via RoleManager) for the first time. In this case, the user either register a new account (via the Register link on the login page), or after authenticated by the organisation's Idp. If using Idp, RoleManager goes through the external log in process discussed above and creates new user account if no existing user is found for the Idp user login.

Single-sign-on with organisation's Idp is achieved by linking the Idp's user login with OneList user account. This process consists of the following steps:

1. Find existing user by UserName if a particular Idp claim is configured for user name match. Common claims for this purpose are SAMAccountName, UPN, prefered_username. 
2. Find existing user by email if the above user name claim is not configured.
3. If an existing user is found, then update the ExternalLogin record for the user, otherwise, create a new user and insert the record to the ExternalLogin table.

Claims required from source system to setup OneList user profile

ADFS configuration

Use OneList root URL as the RelyParty URL, e.g. https://iqx.onelistapprovals.com follow this link for step-by-step instruction at the ADFS side: https://docs.microsoft.com/en-us/aspnet/core/security/authentication/ws-federation?view=aspnetcore-2.2

Use ADFS server Windows Event Log to investigate errors.

Configure RoleManager using the following JSON:

{
"MetadataAddress": "https://adfs.cloud.weir/FederationMetadata/2007-06/FederationMetadata.xml",
"Wtrealm": "https://onelist-dev.cloud.weir/"
}

Azure AD configuration

DO NOT use the .Net MicrosoftAccount provider for Azure AD because it uses OAuth flow and won't be able to get custom claims. Only OIDC flow can retrieve custom claims.

Steps to register OneList on AAD: https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-register-app

The Redirect URI for OneList is: https://iqx.onelistapprovals.com/rolemanager/signin-azure

If OneList is registered for multi-tenant then tenant_id = common

Configure RoleManager using this JSON:

{
"clientid": "xxxxx",
"clientsecret": "xxxx",
"Authority": "https://login.microsoftonline.com/<tenat_id>/v2.0",
"CallbackPath": "/signin-azure",
"Prompt": "select_account",
"SaveTokens": false,
"UserNameClaim": "<custom user name claim>"
}

To avoid auto sign-in, add the following to the JSON.

"Prompt": "select_account"