Skip to main content

SAML with OneLogin

Alex Panagides
Updated

This page shows how to create a OneLogin application for the mxHERO Admin Dashboard and copy OneLogin's values into mxHERO. For background and the full list of SAML values, see Single sign-on with SAML.

Before you begin

  • You need a OneLogin administrator account that can add applications, and an Owner or Administrator user in mxHERO.
  • Copy your mxHERO organization ID from Settings › Organization and domains › Organization (ID). Below it is shown as {organizationId}; the examples use example-inc.
  • Each OneLogin user who will sign in must exist on Settings › Users in mxHERO with the same email address as in OneLogin.

Step 1: Add the application in OneLogin

  1. In the OneLogin admin portal, go to Applications › Applications.
  2. Click Add App.
  3. Search for SAML Custom Connector and select SAML Custom Connector (Advanced).
  4. Enter a Display Name, for example mxHERO Dashboard, and click Save.

Step 2: Configure the application

  1. Open the Configuration tab and enter:

    OneLogin field Value
    Audience (EntityID) https://dashboard-v3.mxhero.com/sp
    Recipient https://dashboard-api.mxhero.com/auth/saml/{organizationId}/sso
    ACS (Consumer) URL Validator A regular expression that matches the ACS URL, for example ^https:\/\/dashboard-api\.mxhero\.com\/auth\/saml\/example-inc\/sso$
    ACS (Consumer) URL https://dashboard-api.mxhero.com/auth/saml/{organizationId}/sso
    Single Logout URL Leave empty
    SAML nameID format Email
    SAML signature element Assertion or Both

  2. Click Save.

  3. Open the Parameters tab and check that NameID value is Email. No other parameters are needed.

Note: Older mxHERO instructions used …/auth/saml/validate as the ACS URL Validator, …/auth/saml/{organizationId}/metadata as the Audience, and …/auth/logout as the Single Logout URL. None of these is correct. Use the values above.

Step 3: Assign users

Give the people who manage mxHERO access to the app, either on each user's Applications tab or through a role that includes the app.

Step 4: Copy OneLogin's values

  1. Open the app's SSO tab.

  2. Copy these values:

    OneLogin value mxHERO field
    Issuer URL Entity ID
    SAML 2.0 Endpoint (HTTP) Single Sign In URL
    X.509 Certificate › View Details (copy the complete certificate) Certificate

Step 5: Turn on SAML in mxHERO

  1. In the Admin Dashboard, open Settings › Security.

  2. On the mxHERO Dashboard card, turn on SAML and click Edit.

  3. Paste the Entity ID, Single Sign In URL and the certificate. Click Save.

    SAML Settings dialog with Entity ID, Single Sign In URL and certificate fields

  4. Click Save Settings. Authenticate again if asked.

Verify

  1. In a private browser window, go to https://dashboard-v3.mxhero.com.
  2. Enter an assigned user's email and choose Use your own domain (SAML).
  3. Sign in to OneLogin. The dashboard opens.

Troubleshooting

Symptom Cause Fix
OneLogin reports an invalid ACS URL The ACS (Consumer) URL Validator regex doesn't match the ACS URL Use the regex above with your organization ID. Escape . and /.
USER_NOT_FOUND NameID isn't the email of an mxHERO user Set NameID value to Email. Add the user in mxHERO with the same address.
ERR_UNMATCH_ISSUER Entity ID in mxHERO isn't the OneLogin Issuer URL Copy the Issuer URL again. Don't use the SAML 2.0 Endpoint here.
ERR_FAILED_MESSAGE_SIGNATURE_VERIFICATION Wrong certificate, or signing turned off Paste the full certificate. Set SAML signature element to Assertion or Both.

Comments

0 comments

Please sign in to leave a comment.

Powered by Zendesk