Configuring Auth0 for Simplelists SAML2 Authentication

Authenticate to Simplelists with Auth0 and SAML2

Work through each section in order – later steps depend on values generated in earlier ones.

Log In to the Auth0 Admin Dashboard

Before you create anything, make sure you are logged into the correct Auth0 tenant. Organizations often have separate tenants for development, staging, and production. Creating the application in the wrong tenant is the most common setup error at this stage, because the metadata URLs and certificate you download later will be specific to that tenant.

• Log on to your Auth0 Admin Console
  • Click Applications under the Application menu
  • Click Create Application

Create Application

This step registers a new application record in Auth0. The application type controls which authentication flows are available – you need Regular Web Application because SAML2 requires a server-side redirect flow, not a single-page or native app flow.

• Enter a Name
• Select Regular Web Application
• Click Create

Give the application a name that clearly identifies it as your Simplelists integration (for example, “Simplelists SAML2”). This name appears in Auth0’s application list and in user consent screens, so something recognizable will save confusion later.

• Click Skip Integration

Configure Application

Now that the application record exists, you need to activate the SAML2 capability within it. Auth0 treats SAML2 as an “addon” – it is not enabled by default. Enabling the toggle creates the SAML2 endpoint and makes the identity provider metadata available.

• Click Addons
• Click toggle for SAML2 Web App

Settings

This section is where you collect the two pieces of information that Simplelists needs about your Auth0 Identity Provider: the metadata XML and the signing certificate. These tell Simplelists where to send users for authentication and how to verify that SAML responses are genuinely from your Auth0 tenant.

From the Configuration Parameters you obtain the Metadata and Certificate.

You can download the following to use with Simplelists:

• Identity Provider Metadata Download
• Identity Provider Certificate: Download Auth0 certificate

Configure the Settings

• Click Settings

Configure

This is the most technically involved step. You are providing Auth0 with the details it needs about Simplelists: where to send the SAML assertion after login (the callback URL), and how to sign and format that assertion. The JSON configuration block defines the audience, the attribute mappings, the signing algorithm, and the certificate used to sign responses.

• Enter the Application Callback URL for Simplelists (Reply URL)
  • The settings are commented out – you need to uncomment the required settings

The following are the minimum settings:

{
 "audience": "https://www.simplelists.com/app/saml/xml",
    "mappings": {
        "email": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress",
        "given_name": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname",
        "family_name": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname"
    },
    "nameIdentifierProbes": [
        "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress"
    ],
    "nameIdentifierFormat": "urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress",
    "signatureAlgorithm": "rsa-sha256",
    "digestAlgorithm": "sha256",
    "signResponse": true,
    "signingCert": "-----BEGIN CERTIFICATE-----\nMIIFHTCCAwWg......weyztkNjtcSi8WD2XEtEeUQ=\n-----END CERTIFICATE-----\n"
}

Why This Matters – Field by Field

The audience value (https://www.simplelists.com/app/saml/xml) is the unique identifier that tells Auth0 which service this SAML assertion is for. If this value does not exactly match what Simplelists expects, Simplelists will reject the assertion as not intended for it – users will see an authentication error even though Auth0 successfully authenticated them.

The mappings block translates Auth0’s internal profile fields into the standard SAML attribute names that Simplelists reads. The email mapping is essential – without it, Simplelists cannot identify which user account to log the user into. The given_name and family_name mappings populate the user’s display name in Simplelists.

The nameIdentifierProbes and nameIdentifierFormat settings tell Auth0 to use the user’s email address as the unique identifier in the SAML assertion (NameID). Simplelists uses this to match the assertion to a specific user account. If the format does not match, logins will fail with an “invalid NameID format” error.

Setting signResponse: true means Auth0 signs the entire SAML response, not just the assertion within it. This provides stronger verification and is required by Simplelists.

The signingCert is the certificate Simplelists uses to verify Auth0’s signature on the SAML response. This must be the certificate from your specific Auth0 tenant (downloaded in the Settings step above) – pasting a certificate from a different tenant or environment will cause signature verification to fail. The single-line formatting requirement exists because JSON does not support multi-line strings; the \n characters represent the line breaks that a PEM certificate normally contains.

User Settings for Name

Auth0 stores users’ given name and family name in a specific way that differs from most identity providers. Because Auth0 does not provide a standard profile form for entering a user’s full name, that information needs to be added manually through the user’s metadata. This step ensures that when Simplelists receives the SAML assertion, it has the name details needed to populate the user’s profile correctly.

• Select User Management
  • Select Users
  • Select the user
  • Scroll down to the Metadata and App Metadata
  • Add the following to both the Metadata and App Metadata:

    {
      "family_name": "Smith",
      "given_name": "John"
    }

  • Click Save

Testing Login

With Auth0 fully configured, this section verifies that the end-to-end login flow works as expected. Testing before rolling out to all users means any misconfiguration can be caught and corrected without impacting anyone else.

• Open the Simplelists web page (https://www.simplelists.com)
• Click Login
• Enter your Auth0-enabled email address and click Submit.

If everything is correctly configured you will be presented with the Auth0 login page.

• Enter the email address that you have enabled for Auth0 in Simplelists
• Enter your password
• Click Sign On

You should be logged into the Simplelists web page as your user.

Use a test user account for your first login rather than an admin account, so that any session or permission issues do not affect your administrative access.

Troubleshooting / FAQs

Related Simplelists SAML2 Guides

Simplelists supports SAML2 single sign-on with all major identity providers. If your organization uses a different identity platform, these guides cover the setup process:

• Configuring a SAML2 Authentication Provider (general guide for any IdP)
• Configuring Azure (Microsoft Entra ID) for Simplelists SAML2
• Configuring ADFS for Simplelists SAML2
• Configuring Shibboleth for Simplelists SAML2

To learn more about Simplelists’ group email products or to start a free trial, visit simplelists.com. If you need help with your SAML2 configuration, get in touch with the Simplelists support team.

References

1. OASIS – Security Assertion Markup Language (SAML) v2.0 Standard
2. OASIS SSTC – SAML V2.0 Technical Overview
3. Auth0 Documentation – Configure Auth0 as SAML Identity Provider
4. Auth0 Blog – What Is SAML and How Does SAML Authentication Work
5. Wikipedia – SAML 2.0
6. Simplelists – Configuring a SAML2 Authentication Provider