Managing Users under Federated Authentication
  • 13 Sep 2022
  • 8 Minutes To Read
  • Dark
    Light
  • PDF

Managing Users under Federated Authentication

  • Dark
    Light
  • PDF

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.

Please be Aware

Once federated authentication is enabled, it cannot be disabled.

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

Please be Aware

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."

Please Note

For any user created in Mambu, the first name, last name, display language, 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 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, all new API users must be created by POSTing to the API 1.0 users endpoint when federated authentication is enabled.

Please Be Aware

You must currently use API 1.0 to create new API users for use with federated authentication. API 2.0 cannot be used for this purpose at this time.

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.
    Editing Role dialog with only API access right checkbox selected.jpg
Please Note

We now offer 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.
Please Note

The mapping system that links the roles in Mambu to your IdP uses the role name. That is why the value for the RoleID attribute is the role name. It is not the role id.

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.

Please Note

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.

The role dropdown in the edit user dialog is not available..jpg

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.

Role dropdown is blank in Edit User dialog.jpg

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."

d3d38d88-d87c-46e4-816e-16c68b333c76.png

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.

Access Preferences

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.

Was this article helpful?