---
title: Integrate with Mautic
sidebar_label: Mautic
support_level: community
---

## What is Mautic

> Mautic provides free and open source marketing automation software available to everyone. Free email marketing and lead management software.
>
> -- https://mautic.org/

## Preparation

The following placeholders are used in this guide:

- `mautic.company` is the FQDN of the Mautic installation.
- `authentik.company` is the FQDN of the authentik installation.
- `mautic-provider` is the [SAML provider](/docs/add-secure-apps/providers/saml) whose settings will be imported into Mautic.

:::info
This documentation lists only the settings that you need to change from their default values.
Be aware that any changes other than those explicitly mentioned in this guide could cause issues accessing your application.
:::

:::warning
Mautic and authentik both require X.509 certificates.
However, Mautic specifically requires the key to contain the phrase `RSA` or `ENCRYPTED` in its header.

See [Troubleshooting](#troubleshooting) if the following error occurs in Mautic:

> Private key is invalid. It should begin with `-----BEGIN RSA PRIVATE KEY-----` or `-----BEGIN ENCRYPTED PRIVATE KEY-----`

:::

## authentik configuration

To support the integration of Mautic with authentik, you need to create property mappings and an application/provider pair in authentik.

### Create property mappings

Because Mautic requires a first name and last name attribute, create two [SAML provider property mappings](/docs/users-sources/sources/property-mappings):

1. Log in to authentik as an administrator and open the authentik Admin interface.
2. Navigate to **Customization** > **Property Mappings** and click **Create**:
    - **Name**: `SAML-FirstName-from-Name`
    - **SAML Attribute Name**: `FirstName`
    - **Expression**:
        ```py
        names = request.user.name.split(" ", 1)
        if (len(names) == 1):
          return ""
        return names[0]
        ```
        This first name mapping will return everything up to the first space (or an empty string if there is no space).
3. Again, click **Create**:
    - **Name**: `SAML-LastName-from-Name`
    - **SAML Attribute Name**: `LastName`
    - **Expression**:
        ```py
        return request.user.name.split(" ", 1)[-1]
        ```
        This second name mapping returns everything after the first space (or the whole name if there is no space).

### Create an application and provider in authentik

1. Log in to authentik as an administrator and open the authentik Admin interface.
2. Navigate to **Applications** > **Applications** and click **New Application** to open the application wizard.
    - **Application**: provide a descriptive name, an optional group for the type of application, the policy engine mode, and optional UI settings.
    - **Choose a Provider**: select **SAML Provider** as the provider type.
    - **Configure the Provider**:
        - Set the **Name** to `mautic-provider`
        - Set the **ACS URL** to `https://mautic.company/s/saml/login_check`
        - Set the **Issuer** to `mautic.company`
        - Set the **Service Provider Binding** to `Post`
        - Under **Advanced protocol settings**, select an available **Signing certificate**, check **Sign assertions** and **Sign responses**, and add the two **Property Mappings** you created in the previous section.
3. Click **Submit** to save the new application and provider.
4. Go to **Applications** > **Providers** and click on `mautic-provider`.
    - Under **Metadata** click on **Download** to save the file as `mautic-provider\_authentik_meta.xml`.

## Mautic configuration

:::info

When running behind an SSL-terminating reverse proxy (e.g. traefik): In **Configuration > System Settings**, make sure that:

- the **Site URL** starts with `https://`
- **trusted proxies** includes the IP-address of the reverse proxy

:::

In **Configuration > User/Authentication Settings**, set the following values:

- **Entity ID for the IDP**: `https://mautic.company`
- **Identity provider metadata file**: The `mautic-provider\_authentik_meta.xml` file
- **Default role for created users**: Choose one to enable creating users.
- **Email**: `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress` (as per provider > preview in authentik)
- **Username**: `http://schemas.goauthentik.io/2021/02/saml/username` (as per provider > preview in authentik)
- **First name**: `FirstName` (as per Provider > Preview in authentik)
- **Last name**: `LastName` (as per Provider > Preview in authentik)
- **X.509 certificate**: The `certificate.crt` file
- **Private key**: The `private_key.pem` file
  Click on **Save**.

## Configuration verification

To confirm that authentik is properly configured with Mautic, open a new incognito/private window or another browser and login at `mautic.company`.
By using an incognito/private window or other browser, you can still access the configuration interface of Mautic if anything went wrong.

## Troubleshooting

### `Uncaught PHP Exception TypeError`

> ```
> mautic.CRITICAL: Uncaught PHP Exception TypeError: "Mautic\UserBundle\Entity\User::getUserIdentifier(): Return value must be of type string, null returned" at /app/bundles/UserBundle/Entity/User.php line 335 {"exception":"[object] (TypeError(code: 0): Mautic\\UserBundle\\Entity\\User::getUserIdentifier(): Return value must be of type string, null returned at /app/bundles/UserBundle/Entity/User.php:335)"}
> ```

This message in Mautic's **System Info > Log in** with an error 500 on its login page indicates a problem with the mapping of the attributes.
(See [Mautic configuration](#mautic-configuration) > Email/Username/First Name/Last Name or [Create property mappings](#create-property-mappings) > Step 2 or [Create an application and provider in authentik](#create-an-application-and-provider-in-authentik) > Step 2.)

### Unable to verify Signature

> Unable to verify Signature

This error occurs when logging in, and indicates that the certificate does not match the private key.
(E.g. when the certificate was generated without the `RSA` and only the private key was changed afterwards.)

### Assertions

> Assertions must be signed

This error occurs when logging in, and indicates that the **Sign assertions** and **Sign responses** settings were not checked in authentik.
(See [Create an application and provider in authentik](#create-an-application-and-provider-in-authentik) > Step 2.)

### Invalid private key

> Private key is invalid. It should begin with `-----BEGIN RSA PRIVATE KEY-----` or `-----BEGIN ENCRYPTED PRIVATE KEY-----`

The private key does not provide the header and footer which Mautic expects.
(E.g., Mautic requires the phrases `RSA` or `ENCRYPTED` in the header and footer.)
To fix this, a new certificate must be generated.
Therefore, follow these steps (where the placeholder `Mautic Self-signed Certificate` is used for the new certificate):

To avoid changing certificates in authentik, go to the authentik Admin interface and generate a new one:

1. Go to **System > Certificates** and click on **Generate**. Use the following values:
    - **Common Name**: `Mautic Self-signed Certificate`
    - **Private key Algorithm**: `RSA`
2. Click the caret (**>**) next to the newly generated certificate, then select **Download certificate** to get the `Mautic Self-signed Certificate\_certificate.pem` file and **Download Private key** to get the `Mautic Self-signed Certificate\_private_key.pem` file.
3. Make sure that the `Mautic Self-signed Certificate\_private_key.pem` is in PKCS#1 format.
   To verify, use `grep` to check for `RSA` in the header and footer of the file:
    ```sh
    grep "RSA PRIVATE KEY" "Mautic Self-signed Certificate_private_key.pem"
    ```
    If the command returns the correct match (e.g., `-----BEGIN RSA PRIVATE KEY-----` and `-----END RSA PRIVATE KEY-----`), the key is in PKCS#1 format, and you can skip steps 4 to 6.
4. If the key is not in PKCS#1 format, add RSA after `BEGIN` and `END` in `Mautic Self-signed Certificate\_private_key.pem` as shown below and save the file as `private_key_new.pem`:
    ```diff
    - -----BEGIN PRIVATE KEY-----
    + -----BEGIN RSA PRIVATE KEY-----
    ```
    and
    ```diff
    - -----END PRIVATE KEY-----
    + -----END RSA PRIVATE KEY-----
    ```
5. Regenerate the X.509-certificate by first creating a signing request, using the following command:

    ```sh
    openssl req -new -key private_key_new.pem -out request.csr
    ```

    This will prompt you to enter values for the certificate which you can choose freely.
    For some, you can use authentik's generated values:
    - **Organization Name**: `authentik`
    - **Organizational Unit Name**: `Self-signed`
    - **Common Name**: `Mautic Self-signed Certificate`

6. Next, generate the certificate with the (now) PKCS#1-compliant key and the previously generated signing request using the following command:

    ```sh
    openssl x509 -req -days 365 -in request.csr -signkey private_key_new.pem -out certificate_new.pem
    ```

7. In authentik, navigate to **System > Certificates** and click **Edit** on the previously generated certificate.
   Click on the description below the text inputs to activate the inputs.
    - **Certificate**: Enter the contents of `certificate_new.pem` or, if steps 4 to 6 were skipped, `Mautic Self-signed Certificate\_certificate.pem`
    - **Private Key**: Enter the contents of `private_key_new.pem` or, if steps 4 to 6 were skipped, `Mautic Self-signed Certificate\_private_key.pem`
    - Click on **Update**
8. Navigate to **Applications > Providers** and **Edit** `mautic-provider` (which was created in [Create an application and provider in authentik](#create-an-application-and-provider-in-authentik)).
   In **Advanced protocol settings**, change **Signing Certificate** to `Mautic Self-signed Certificate`
9. Save the provider, view it, and download the metadata file to `mautic-provider\_authentik_meta.xml`
10. In Mautic, navigate to **Configuration > User/Authentication Settings** and set the following values:

- **X.509 certificate**: The `certificate_new.crt` file
- **Private key**: The `private_key_new.pem` file
- **Identity provider metadata file**: The new `mautic-provider\_authentik_meta.xml` file

11. Click on **Save**.
