Enabling Federated Authentication with Mambu

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

Mambu login is the default authentication system. You are provided with a username and password managed through our system.

Federated authentication on the other hand 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, Centrify, metOneLogin, or Google. Then they are able to access a variety of web applications without re-entering their username and password.

The Mambu federated authentication feature is based on SAML 2.0 (Security Assertion Markup Language).

How we implemented SAML 2.0 in Mambu

Our implementation uses a SAML 2.0 redirect profile.
All SAML requests are resolved via the user’s browser.

Steps:

1. User wants to login to Mambu via IdP (a GET request is initiated to Mambu, SAML, or login endpoint). At our end, we prepare a SAML request that is sent to the user's browser.
2. The SAML request for login is sent to the IdP.
3. User logins to the IdP.
4. A SAML response is prepared at the IdP's end and sent to the user's browser.
5. The SAML response is posted to Mambu, SAML, or login endpoint. Depending on the SAML response (which is verified for authenticity) we either start a Mambu session or not.

General Setup

Step 1. Configure the IdP

First, create a new Mambu SAML application in your IdP. This application will communicate with Mambu.

If you regularly use sandboxes to test new features, it might make sense to already create an application for your Mambu Sandbox instance now, too. See below for more information on using federated authentication with a sandbox instance.

Step 2. Assign Users to the SAML 2.0 Application

Import the existing Mambu users in the IdP by getting the usernames from the database or create your Mambu users in the IdP of choice using the same username. We will map the existing users into the IdP based on their unique username and we will make sure they have the same level of access (permissions and roles) once you enable federated authentication.

Step 3. Enable Federated Authentication in Mambu

1. On the main menu, go to Administration > Access > Federated Authentication.

2. Select the Enable Single Sign-On checkbox.
3. Enter all the necessary information:

4. Select Test SSO Connection to verify that setup is correct and the communication between Mambu and the IdP is successful.
5. Select Save Changes. In the Confirm Federated Authentication Setup dialog, select Yes.

Now a SAML conversation is started between Mambu and the IdP. The setup of Single Sign-On is now complete.

Once you enable the federated authentication feature, the Mambu login form will include a link at the bottom that allows you to log in with your IdP. The IdP name will be whatever text you entered in the Name field during setup.

Using sandboxes with federated authentication

To use a sandbox with federated authentication enabled, you will need to create a separate application in your IdP, such as a "Mambu Sandbox" application with its own certificate fingerprint and single sign-on endpoint. To create such an application, follow the same steps that you used to set up your production instance, as described in General Setup.

This is necessary because, if you do not, when you clone a production instance to a sandbox and try to log in using federated authentication, the login request will come from a different domain and will be rejected.

Remember, you may not need to add all users to this application, just those who are going to be accessing the sandbox.

Each time you clone your production instance to your sandbox, you will need to update the federated authentication settings to point to the Mambu Sandbox application you created in your IdP. In order to do this you will need to have at least one user with administrator permissions.

To update the federated authentication settings:

1. On the main menu, go to Administration > Access > Federated Authentication.
2. Replace the cloned production data with the single sign-on endpoint, certificate fingerprint and Issuer ID for your Mambu Sandbox application.
3. Select Save Changes.

Using SSO under a proxy

To use SSO when the Mambu application is running under proxy, you need to do the following:

1. Configure the proxy to pass the x-mambu-proxy-host header to Mambu. The header should point to the proxy host and not the Mambu host.
2. If the proxy is configured to pass the proxy host in the host header to Mambu, this configuration should be removed. When the proxy is forwarding requests to Mambu the host header should be the Mambu host.

Example

If your Mambu instance is https://mybank.mambu.com and it is running under a proxy at https://theproxyaddress.com, the requests should be forwarded to Mambu with the following headers:

• The x-mambu-proxy-host should be https://theproxyaddress.com.
• The host value should be https://mybank.mambu.com.