- 10 Oct 2023
- 5 Minutes To Read
- Print
- DarkLight
- PDF
Enabling Federated Authentication with Mambu
- Updated On 10 Oct 2023
- 5 Minutes To Read
- Print
- DarkLight
- PDF
Mambu offers two authentication options: Mambu login and federated authentication. Mambu login uses a username and password managed internally, while federated authentication allows Single Sign-On through providers like Okta or Google. The federated authentication is based on SAML 2.0. To set up federated authentication, configure the IdP, assign users to the SAML 2.0 application, and enable it in Mambu settings. Testing the SSO connection is crucial. Sandboxes require a separate application in the IdP. When using SSO under a proxy, ensure the correct headers are configured. Regular updates are needed when cloning production instances to sandboxes.
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).
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
Our implementation uses a SAML 2.0 redirect profile.
All SAML requests are resolved via the user’s browser.
Steps:
- 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.
- The SAML request for login is sent to the IdP.
- User logins to the IdP.
- A SAML response is prepared at the IdP's end and sent to the user's browser.
- 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.
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.
We recommend consulting your IdP's documentation for more information on setting up the relevant configuration for IdP certificate signature verification.
General Setup
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 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.
- On the main menu, go to Administration > Access > Federated Authentication.
- Select the Enable Single Sign-On checkbox.
- Enter all the necessary information:
Field | Description | Required? |
---|---|---|
Name | Name for the IdP. Displayed on the "log in using your IdP" link provided in by Mambu. | ✔ |
Single Sign-On Endpoint | SSO endpoint available from your IdP settings. Select the Private Identity Provider checkbox if your IdP is not publicly available. | ✔ |
Certificate Fingerprint | When 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 ID | The URL that contains the domain name of the IdP. It must have the format https:// or http:// . | ✔ |
ACS URL | The 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. | ✘ |
- Select Test SSO Connection to verify that setup is correct and the communication between Mambu and the IdP is successful.
- 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.
- 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:
- On the main menu, go to Administration > Access > Federated Authentication.
- Replace the cloned production data with the single sign-on endpoint, certificate fingerprint and Issuer ID for your Mambu Sandbox application.
- 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:
- 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. - 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 behttps://theproxyaddress.com
. - The
host
value should behttps://mybank.mambu.com
.