Enabling Federated Authentication with Mambu
  • 10 Oct 2023
  • 5 Minutes To Read
  • Dark
  • PDF

Enabling Federated Authentication with Mambu

  • Dark
  • PDF

Article Summary

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

Please be Aware

Transitioning to federated authentication is irreversible. Administrators and users with API access will still have access to Mambu login however all other users will have to log in through their IdP.

How we implemented SAML 2.0 in Mambu

Diagram of SAML redirect process between user, Mambu, and identity provider

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


  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.
Please Note

All SAML 2.0 authentication requests made by the Mambu application to your IdP are signed. To download the certificate that allows you to verify the signature of Mambu requests, go to Administration > Access > Federated Authentication and select Download.

Download signature button

We recommend consulting your IdP's documentation for more information on setting up the relevant configuration for IdP certificate signature verification.

General Setup

Please Note

If you are using one of our most common IdPs then please refer to our step-by-step guides provided for Google Apps, Azure Active Directory, Centrify, OneLogin, or Okta. Otherwise you can follow the more general steps below.

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

Please be Aware

Please initiate the login from the Mambu login form. We do not support IdP-initiated login.

Also, you must be an administrator to set up federated authentication.

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

Federated Authentication tab with Enable Single Sign-On check-box

  1. Select the Enable Single Sign-On checkbox.
  2. Enter all the necessary information:
NameName for the IdP. Displayed on the "log in using your IdP" link provided in by Mambu.
Single Sign-On EndpointSSO endpoint available from your IdP settings. Select the Private Identity Provider checkbox if your IdP is not publicly available.
Certificate FingerprintWhen you set up your IdP, you will download a certificate. To get a SHA-256 fingerprint from this certificate, use the follow command: openssl x509 -noout -fingerprint -sha256 -inform pem -in {/path/to/certificate-file.crt}. Replace the placeholder in curly braces with the actual path to your certificate file.
Issuer IDThe URL that contains the domain name of the IdP. It must have the format https:// or http://.
ACS URLThe URL where your application is hosted. This field is required when using a reverse proxy, or when using an IdP with a dedicated environment. This will correlate the response with the original AuthRequest. It must match the ACS URL and Entity ID configured in your IdP.

Single Sign-On options screen

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

confirm federated authentication setup dialog

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.

Please be Aware
  • When federated authentication is enabled, you can no longer create new users from the Mambu UI, and will have to create new users in your IdP. We will automatically provision new users into Mambu during their first login.
  • You may continue creating users with API permissions through the Mambu Users API, but they must have a role set up as well.

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.


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.

Was this article helpful?