Managing Users under Federated Authentication

There are two types of authentication available in Mambu, Mambu login and federated authentication.

Federated authentication allows users to connect to Mambu using Single Sign-On (SSO). With SSO, users authenticate through an Identity Provider (IdP) such as Okta, Azure Active Directory, Centify, OneLogin, or Google. Then they are able to access a variety of web applications without re-entering their username and password.

If the federated authentication feature is enabled, the way you manage users in Mambu will change.

Regular users

Regular users are Mambu users who do not have admin rights.

If your organization has already created Mambu users before enabling federated authentication, you will have two kinds of users after the feature is enabled: users created in Mambu, and users created in your IdP. Users created in Mambu will now switch from using Mambu login to using SSO to log in to Mambu. Users initially created in your IdP will only log in to Mambu using SSO.

Creating regular users

Once you enable federated authentication, you must create new regular users from your IdP. You will no longer be able to create new regular users from the Mambu UI, even if you previously had the Create Users permission. The option to create users will no longer be available in the Create dropdown or in Administration > Access > Users.

Managing regular users created in Mambu

Once federated authentication is enabled, regular users will no longer be able to log in to Mambu with their username and password. They will have to log in to Mambu using SSO.

For each user with access to Mambu who was initially created in the Mambu UI, you must create a corresponding user in your IdP using the same email address and assign them to the Mambu SAML App. Please refer to the documentation for your IdP for more information on how to set up new users.

These users will have Mambu credentials, but they will no longer be able to use them to log in to Mambu. If they attempt to do so, they will receive the error message "Sorry, your username and password appears to be incorrect. Please try again or contact your admin."

For any user created in Mambu, the first name, last name, display language, branch, and role defined in the IdP will override the values previously defined in Mambu.

Managing regular users created in your IdP

After federated authentication is enabled, you must create new regular users from your IdP. Please refer to the documentation for your particular IdP for more information on how to set up new users.

Make sure that each user has a unique email address, and once you have created them, assign them to the Mambu SAML App. If your user does not have a unique email address, then you will receive the message "Email address of the users is not unique. Email duplication is not allowed."

You must also define the display language for the Mambu UI in your IdP. For more information, see Language Settings.

Finally, when you create a new user you must assign them a role.

API Users

Every Mambu API user must have a username and password in order to make API calls. However, users created in your IdP will not have a password managed by Mambu.

For this reason, API users must have API Access as their only assigned role. Otherwise, when you attempt to create an API user that also has access to Mambu, you will receive the error message:

{
    "returnCode": 3500,
    "returnStatus": "CANNOT_CREATE_NEW_USER_IN_FEDERATED_CONTEXT"
}

To create a new API user:

1. On the main menu, go to Administration > Access > Roles.
2. Either edit an existing role, or select Add Role to create a new role.
3. Create a role and select API under Access Rights. You must leave the Mambu checkbox unselected, as shown below.
4. Use the users endpoint, and make sure to assign the role you created in the last step.
   

In addition to API users, you may also use API Consumers as an alternative to user-based access control, and we recommend that anyone using federated authentication use API Consumers to request access credentials instead of users. For more information, see API Consumers.

Admin Users

When you enable federated authentication, regular users may no longer log in to Mambu using their username and password. However, admin users may continue to do so.

Creating admin users

There are two ways to create a new admin user:

• Assign an existing user the Administrator user type, or
• Assign an existing user a role that includes Administrator permissions. For more information on roles, see Roles below.

To assign the Administrator user type to an existing user:

1. Create a new user in your IdP.
2. Log in to Mambu with the new account to provision the user in Mambu. The user will have no role or permissions, and therefore no access to the Mambu platform.
3. Log out, and log back in to Mambu with any administrator account.
4. On the main menu, go to Administration > Access > Users.
5. Find the new user you created in your IdP in the list of users and select Actions > Edit.
6. In User Rights, select the Administrator checkbox.
7. Select Save Changes.

To create a new user with a role that includes Administrator permissions:

1. If you do not already have an appropriate Mambu role with Administrator permissions that you can assign to the new user, create one now.
2. Create a role in your IdP and give it the same name as the Mambu role that has Administrator permissions.
3. Create a new user in your IdP. In the RoleID attribute, assign the role with Administrator permissions.
4. Log out, and log back in to Mambu with your new user credentials. After the first successful login, a new user with admin rights will be provisioned in Mambu.

Roles

Every user in Mambu is assigned permissions, which determine what the user is able to see and do. You can group a set of permissions together in a role, and assign roles to users.

Setting up user roles

To set up user roles:

1. Create roles in Mambu: you must create all the roles you want to use in the Mambu UI. For more information on creating roles, see Roles.
2. Create roles in IdP: you must create all the roles you have in Mambu UI that you want to use in your IdP as well. The SAML attribute in the IdP will be called RoleID. The value of the RoleID attribute should be the role name.
3. Assign roles to users in IdP: every user must have a role assigned to them from your IdP even if they previously had a role defined in Mambu.

We check the RoleID attribute at each login so any changes to a user's role made in the IdP will be reflected in Mambu as well.

Moreover, different IdPs may use different terms to describe what we call "roles". For example, roles are called Groups in Okta or appRoles in Azure AD.

Managing user roles

You must assign a role with the RoleID attribute to every user in your IdP, whether they were created in Mambu or from you IdP.

After federated authentication is enabled, in case of a conflict, roles assigned in the IdP override roles that were previously assigned in Mambu. You will also no longer be able to edit a user's roles in Mambu. If you select to edit a user and open the Edit User dialog, you will find the Role dropdown is not available.

If you do not specify a role in your IdP using the RoleID attribute and your user has no other permissions, then your user will not be able to access Mambu. If they were created in Mambu with a role defined in Mambu, then that role will be automatically removed.

If the user attempts to log in to Mambu they will not be able to log in and they will receive the warning message "Please ask the administrator to assign the appropriate permissions into ORGANIZATION_NAME as per your role. This will ensure you'll get access to the most common features and you are ready to start enjoying the range of services available in ORGANIZATION_NAME."

Branch assignment

For customers that have federated authentication enabled, branch assignment is managed using your identity provider (IdP).

The following are the general steps to assign a branch to an existing user using your IdP:

1. In your IdP, create a custom attribute with the label BranchID.
2. If necessary, set up the mapping for the BranchID custom attribute in your IdP to the BranchID attribute in Mambu. This process is similar to the process of mapping the RoleID custom attribute.
3. Go to each user profile in your IdP and add the relevant value for BranchID using the ID of an existing branch.

Any further updates to the branch a user is assigned to must be carried out using your IdP.

For more information on how to carry out branch assignment using a specific IdP, see the following relevant sections:

• Branch assignment using Azure AD as your IdP
• Branch assignment using Google as your IdP

Branch assignment and branch access

Only branch assignment is managed using your IdP. Branch access is still managed using the Mambu UI or API v2.

Branch assignment is managed in the Assigned To section of the user form. Whereas, branch access is managed in the Access Rights section of the user form.

For more information about these sections of the user form, see Creating a User.

Access Preferences

Managing session expiration time

You can define a session expiration time for your IdP and for Mambu UI.

In Mambu, the timeout session field sets the amount of time a user can be inactive before they are automatically logged out.

The session expirations times for Mambu and your IdP are independent from one another. Once you log in to Mambu, the system will only take into account your Mambu session expiration time.

To define the Mambu session expiration time:

1. On the main menu, go to Administration > Access > Preferences.
2. Under Timeout Session, enter the amount of minutes you want your session time to last.
3. Select Save Changes.

Managing critical action re-authentication

A critical action is a function that Mambu considers business critical. For more information on critical actions, and a list of them, see Actions considered critical in Mambu.

If critical action re-authentication is enabled, users are required to authenticate when they perform critical actions in the system.

When federated authentication is enabled, regular users are redirected to their IdP to authenticate. Admin users may also use Mambu credentials to authenticate. If federated authentication is not enabled, a Confirm Identity dialog appears and users are required to provide their credentials when they perform critical actions in the system.

Note that some IdPs (such as Google) use pre-logged-in sessions instead of enforcing re-authentication.

To enable or disable critical action re-authentication:

1. On the main menu, go to Administration > Access > Preferences.
2. Under Critical Actions Re-Authentication, select or clear the Require Admin Password checkbox.
3. Select Save Changes.