ContextQMD
Back to Authentik

Integrate with Mautic

website/integrations/chat-communication-collaboration/mautic/index.md

latest10.1 KB
Original Source

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 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 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:

  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 Create with Provider to create an application and provider pair. (Alternatively you can first create a provider separately, then create the application and connect it with the provider.)
    • 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 > Email/Username/First Name/Last Name or Create property mappings > Step 2 or 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 > 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). 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
  1. Click on Save.