Single Sign-On with SAML

You can let Admin Dashboard users sign in through your own identity provider (IdP) with SAML 2.0, for example Okta, OneLogin or Microsoft Entra ID. This page lists the values mxHERO needs in your IdP, the values your IdP gives back, and how to turn SAML on in the dashboard.

SAML applies to the Admin Dashboard only. End User App sign-in is set separately in Settings › Security. See Security settings.

Before you begin

• You need an Owner or Administrator user in mxHERO, and an administrator in your IdP who can create SAML applications.
• Find your mxHERO organization ID: Settings › Organization and domains › Organization, shown as ID under your organization name. In this page it appears as {organizationId}, for example example-inc.
• Every person who will sign in with SAML must already exist on Settings › Users with the same email address they have in your IdP. mxHERO does not create users from SAML.
• Keep User and Password (or another method) on while you test, so you can't lock yourself out.

Values to enter in your identity provider

mxHERO uses one service-provider (SP) identity for every IdP.

For example, for organization ID example-inc the ACS URL is https://dashboard-api.mxhero.com/auth/saml/example-inc/sso.

mxHERO also publishes SP metadata at https://dashboard-api.mxhero.com/auth/saml/{organizationId}/metadata. It is available only after SAML has been saved for your organization, so most IdPs are set up with the values above instead.

Values to get from your identity provider

IdP-specific steps:

• SAML with Okta
• SAML with OneLogin
• SAML with Microsoft Entra ID

Turn on SAML in mxHERO

1. Open Settings › Security.

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

3. In SAML Settings, enter:

   • Entity ID: the IdP entity ID / issuer.
   • Single Sign In URL: the IdP SSO URL.
   • The certificate: paste the complete X.509 certificate.

   

4. Click Save in the dialog.

5. Click Save Settings on the card. If asked, authenticate again.

After the first save, the certificate is hidden. To keep it, leave Change certificate empty when you edit the settings later. To replace it, paste the new certificate.

How sign-in works

1. The user enters their email on https://dashboard-v3.mxhero.com and chooses Use your own domain (SAML). If SAML is the only method, they go to the IdP automatically.
2. The IdP authenticates the user and posts a signed response to the ACS URL.
3. mxHERO checks the issuer, the signature and the time window, then signs in the user whose email matches the Name ID.
4. If 2FA is on, the user also enters an emailed code.

Users can also start from the mxHERO tile in the IdP's portal (IdP-initiated sign-in).

Signing out of mxHERO ends only the mxHERO session. It doesn't sign the user out of the IdP.

Verify

1. Assign a test user to the mxHERO application in your IdP. The user must exist on Settings › Users.
2. In a private browser window, go to https://dashboard-v3.mxhero.com, enter the test user's email, and choose Use your own domain (SAML).
3. The dashboard opens after the IdP sign-in.
4. In Reports › User Activity, the login event shows the SAML method.

When SAML works for everyone, you can turn other methods off in Settings › Security.

Troubleshooting

Errors appear on the page you return to after the IdP.

Related pages

• Security settings
• Users and roles
• Registering and signing in
• User Activity