User authentication

User Authentication allows you to control how end-users authenticate with the Mambo platform. This guide helps you choose and configure the right authentication method for your implementation.

Why authentication matters

Authentication determines:

• How users access the User Portal
• Security level of your implementation
• Integration complexity with existing systems
• User experience during login

Authentication methods overview

Mambo offers multiple authentication options to accommodate different security requirements and implementation scenarios:

Method	User directory	Complexity	Best for	User portal compatible
No Authentication	None	Low	API-only implementations	No
Mambo Internal	Mambo	Low	Simple implementations	Yes
LDAP	External	Medium	Enterprise with LDAP	Yes
SAML	External	Medium	SSO implementations	Yes
JWT	External	Medium	Custom UIs	Depends

No authentication (default)

This is the platform's default setting and requires no user authentication mechanism. Choose this option when:

• Your users don't need access to the User Portal
• You're building a custom integration using backend API calls
• You want to minimise implementation complexity

With this option:

• User identity is managed entirely through your systems
• All communication with Mambo occurs via your backend using API keys
• End users never authenticate directly with Mambo

Implementation considerations:

• Keep API keys secure in your backend environment
• Use API key roles to limit access to specific functions
• Consider proxying widget requests through your backend

Mambo internal directory

The Mambo internal directory stores user credentials directly within the Mambo platform. Choose this option when:

• You need a simple authentication solution
• You don't have an existing user directory
• You want to provide User Portal access with minimal setup

With this option:

• Users authenticate using their UUID as username and a password configured in Mambo
• Successful login grants access to the User Portal or a custom page you specify
• Credentials are managed within the Mambo platform

Setup requirements:

1. Enable the Mambo internal directory in Authentication settings
2. Note the custom login URL provided in the "New Login Address" section
3. Share this specific URL with your users, as they cannot log in through other addresses
4. Configure redirect destinations after successful login

LDAP directory

Connect Mambo to any LDAP-compatible user directory such as Microsoft Active Directory. Choose this option when:

• Your organisation already uses LDAP for authentication
• You need to maintain a single source of user credentials
• You require enterprise-grade directory integration

Setup requirements:

1. Configure connection details on the Authentication page
2. Test the connection before saving
3. Note the custom login URL provided in the "New Login Address" section
4. Share this specific URL with your users, as they cannot log in through other addresses
5. Configure redirect destinations after successful login

SAML directory

Connect Mambo to any SAML-compatible identity provider such as Okta, Google or Azure Active Directory. Choose this option when:

• Your organisation uses a SAML-based single sign-on solution
• You want to leverage existing authentication workflows
• You require enterprise-grade security

Setup requirements:

1. Configure SAML settings on the Authentication page
2. Set up Mambo as a service provider in your identity provider
3. Note the custom login URL provided in the "New Login Address" section
4. Share this specific URL with your users, as they cannot log in through other addresses
5. Configure redirect destinations after successful login

For detailed configuration examples with common providers, see the administrator Authentication section.

JWT authentication

JSON Web Token (JWT) authentication allows individual API requests to be authenticated using tokens issued by your identity provider. Choose this option when:

• You're building a custom UI integration
• You prefer token-based authentication for API requests
• You want to leverage your existing authentication system

With this option:

• Users authenticate with your identity provider, not directly with Mambo
• Your system generates JWT tokens that are included with each API request
• No separate login with Mambo is required

Implementation methods

You can include the JWT token as either query parameters or request headers:

Query parameters:

HTTP

t=<insert_tenant>&s=<insert_site>&jwt=<insert_token>

Request headers:

HTTP

X-Mambo-Tenant: <insert_tenant>
X-Mambo-Site-Url: <insert_site>
Authorization: Bearer <insert_token>

Note: The tenant and site values will be provided in the Authentication page when configuring JWT Authentication.

Choosing the right authentication method

Consider these factors when selecting an authentication approach:

1. User Portal requirements

   • If users need direct access to the User Portal, you'll need an authentication method other than "No Authentication"

2. Integration complexity

   • For simple implementations, consider Mambo internal directory
   • For enterprise integrations, LDAP or SAML may be more appropriate
   • For custom UIs, JWT authentication offers flexibility with existing systems

3. Security requirements

   • Backend-only integration with API keys offers clean separation of concerns
   • SAML and LDAP leverage enterprise-grade directory services
   • JWT provides granular request-level authentication

4. Existing infrastructure

   • Leverage your existing user directory when possible for simplicity

Troubleshooting authentication

Common authentication issues and solutions:

• Users can't log in: Ensure they're using the specific login URL provided in the "New Login Address" section
• JWT tokens rejected: Verify token format and signing key configuration
• LDAP connection failing: Check network connectivity and credential permissions
• SAML errors: Confirm metadata configuration matches between Mambo and your identity provider

Next steps

After configuring authentication:

1. Set up user management workflows
2. Configure administrator access
3. Explore user portal customisation

---

Related topics

• API keys
• User portal
• Widgets
• User management