Authentication

Mautic uses basic authentication for Users, however there is the ability to integrate with a SAML SSO - Single Sign-On - provider.

SAML Single Sign On

SAML is a single sign on protocol that allows single sign on and User creation in Mautic using a third party User source called an identity provider (IDP).

Turning on SAML

To turn on SAML support in Mautic, you first need the IDP’s metadata XML which they provide. If it’s a URL, browse to the URL then save the content into an XML file.

  1. Click the settings wheel in the top right corner to open the Settings menu.

  2. Navigate to Configuration > User/Authentication Settings.

Screenshot of SAML SSO Settings

  1. Upload this file as the Identity Provider Metadata file.

  2. It’s recommended to create a non-Admin Role as the default Role for created Users. Select this Role in the ‘Default Role for created Users’ dropdown. For more information, see Users and Roles.

Screenshot of the User Role Permission

Configuring the IDP

The IDP may ask for the following settings:

  1. Entity ID - This is the site URL, displayed at the top of User/Authentication Settings. Copy this exactly as is to the IDP.

    Note

    If you use a custom domain, set the site URL in Configuration > System Settings to match it. This keeps your SAML setup working correctly.

  2. Service Provider Metadata - If the provider requires a URL, use https://example.com/saml/metadata.xml. If it needs a file instead of a URL, open the URL in a browser and save the content as an XML file.

  3. Assertion Consumer Service - Use https://example.com/s/saml/login_check.

  4. Issuer - It should come from the IDP but is often configurable. If it’s a URL, be sure that the scheme - http:// or https:// - isn’t part of it.

  5. Verify request signatures or an SSL certificate - If the IDP supports encrypting and validating request signatures from Mautic to the IDP, generate a self-signed SSL certificate. Upload the certificate and private key through Mautic’s Configuration > User/Authentication Settings under the “Use a custom X.509 certificate and private key to secure communication between Mautic and the IDP” section. Then upload the certificate to the IDP.

  6. Custom attributes - Mautic requires three custom attributes in the IDP responses - email, first name, and last name - and can optionally include a username. Configure the attribute names used by the IDP in Mautic’s Configuration > User/Authentication Settings under the “Enter the names of the attributes the configured IDP uses for the following Mautic User fields” section.

Example - Azure SAML SSO

  1. Register a new application by going to Enterprise Applications, clicking Create your own application, and selecting Integrate any other application you don’t find in the gallery (Non-gallery).

  2. Go to the Single sign-on menu.

  3. Entity ID - This is the site URL, displayed at the top of User/Authentication Settings. Copy this exactly as is to the IDP.

  4. Reply URL (Assertion Consumer Service URL) - Use https://example.com/s/saml/login_check.

  5. In the SAML Certificates section, download the Federation Metadata XML.

  6. Upload the downloaded Federation Metadata XML file to the Identity provider metadata file field in Mautic, and leave the X.509 Certificate field blank.

  7. Use the following for the custom attributes fields:

    • E-Mail: http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress

    • First Name: http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname

    • Last Name: http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname

    • Username (optional): http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name

Logging in

Once configured with the IDP and the IDP with Mautic, Mautic redirects all logins to the IDP’s login. /s/login is still available for direct logins but you have to access it directly.

Login to the IDP, which then redirects you back to Mautic. If the exchange is successful Mautic creates a User if it doesn’t already exist, and logs the User into the system.

Managing passwords for SAML-authenticated Users

Mautic hides the password fields on the Account page and User edit form for SAML-authenticated Users. SAML-authenticated Users log in through the identity provider, so they manage their passwords there, not in Mautic.

Recovering from a login error

A SAML login can fail if the session expires or if Mautic receives an unexpected response from the IDP, such as the intermittent ‘Unknown Response’ error. When this happens, Mautic clears the session and shows a retry screen. Select the login button to try again. If the error keeps happening, contact your administrator.

Turning off SAML

To turn off SAML, click the Remove link to the right of the Identity provider metadata file label.

Screenshot of the authentication settings section