Skip to main content

SAML with Okta

Alex Panagides
Updated

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

Before you begin

  • You need an Okta administrator account that can create app integrations, 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}.
  • Each Okta user who will sign in must exist on Settings › Users in mxHERO with the same email address as their Okta username.

Step 1: Create the app integration in Okta

  1. In the Okta Admin Console, go to Applications › Applications.

  2. Click Create App Integration.

  3. Select SAML 2.0 and click Next.

  4. General Settings: enter an App name, for example mxHERO Dashboard. Click Next.

  5. Configure SAML › General:

    Okta field Value
    Single sign-on URL https://dashboard-api.mxhero.com/auth/saml/{organizationId}/sso
    Use this for Recipient URL and Destination URL Selected
    Audience URI (SP Entity ID) https://dashboard-v3.mxhero.com/sp
    Default RelayState Leave empty
    Name ID format EmailAddress
    Application username Email

    No attribute statements are needed. Leave the advanced settings at their defaults (signed response and assertion).

  6. Click Next, choose the feedback option that fits (for example, an internal app), and click Finish.

Note: Older mxHERO instructions used https://dashboard-api.mxhero.com/auth/saml/{organizationId}/metadata as the Audience URI. Use https://dashboard-v3.mxhero.com/sp instead.

Step 2: Assign users

  1. In the new app, open the Assignments tab.
  2. Click Assign › Assign to People or Assign to Groups, and add the people who manage mxHERO.
  3. Click Done.

Step 3: Copy Okta's values

  1. Open the app's Sign On tab.

  2. Under SAML 2.0, open the setup instructions (View SAML setup instructions, or More details in newer consoles).

  3. Copy these values:

    Okta value mxHERO field
    Identity Provider Issuer (also Issuer) Entity ID
    Identity Provider Single Sign-On URL (also Sign on URL) Single Sign In URL
    X.509 Certificate (complete, including the BEGIN CERTIFICATE and END CERTIFICATE lines) Certificate

Step 4: 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 filled with example Okta values

  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 Okta. The dashboard opens.

You can also open the mxHERO tile from the Okta End-User Dashboard.

Troubleshooting

Symptom Cause Fix
USER_NOT_FOUND The Okta username isn't the email of an mxHERO user, or Application username isn't Email Set Application username to Email. Add the user in mxHERO with the same address.
ERR_UNMATCH_ISSUER Entity ID in mxHERO isn't the Okta Identity Provider Issuer Copy the issuer again (it looks like http://www.okta.com/...).
ERR_FAILED_MESSAGE_SIGNATURE_VERIFICATION Wrong or partial certificate Paste the complete X.509 certificate from the app's Sign On tab.
Okta says you aren't assigned to the app User not assigned Assign the user or their group (Step 2).

Comments

0 comments

Please sign in to leave a comment.

Powered by Zendesk