Setting up Okta SSO

View as Markdown

Superusers can set up single sign-on to the runZero Console through an external SAML identity provider (IdP) such as Okta. The IdP then handles authentication and user access control, and your users sign in without typing credentials.

Setting up single sign-on (SSO) with Okta takes these high-level steps:

Requirements

Before you can set up Okta SAML:

  • Confirm that you have administrator privileges for Okta.
  • Confirm that you are a superuser in runZero. Look for the yellow star in your account status.

Step 1: Add and configure runZero as an Okta app

  1. Go to Okta > Applications > Create App Integration. In the Create a new app integration window, select SAML 2.0 as your sign-in method. Sign-in method
  2. In the general settings, name the app runZero. You can also add a logo so users can pick out the runZero app.
  3. For the SAML settings, open the service provider information page in runZero to find the URLs you need.
    • Single sign on URL is the assertion consumer service (ACS) URL shown in runZero.
    • Audience URI or SIP Entity ID is the runZero entity ID, or SAML audience: https://console.runzero.com.
      • Include the leading ‘https://’ when you enter this field in Okta.
  4. For the remaining settings, such as the attribute statements, the Okta documentation explains how to configure them.
  5. Once the SAML settings are done, Okta asks for feedback on how you will use the app. Answer or skip it to finish creating the app.
  6. After Okta creates the app, go to the Sign On tab for the runZero app and open the SAML 2.0 instructions. You’ll need these details in the next step.

Okta SAML instructions

Step 2: Set up SSO in runZero

  1. Go to the SSO setup page in runZero and choose a mode to enable SSO:
    • Allowed enables SSO but still lets users sign in without it.
    • Required makes users sign in with SSO. Only superusers can sign in without it.
  2. Enter the domain name associated with SSO authentication. This is likely your company domain (companyabc.com).
  3. Choose a default role for SSO users. runZero assigns this role to every new user when it creates their account.
  4. Copy the fields from Okta into runZero.
    • Issuer URL takes the Identity Provider Issuer URL from Okta. It looks something like http://www.okta.com/<ID>.
    • Sign-in URL takes the Identity Provider Single Sign-On URL from Okta. It looks something like http://<okta-instance>/app/<app-name>/<ID>/sso/saml.
    • Certificate holds the X.509 certificate from Okta. Paste its entire contents.
  5. Apply your SSO settings.

Step 3: Add users to the runZero app in Okta

With setup complete, go to the runZero app in Okta to add and manage user access. Once added, your users can reach runZero from your SSO sign-in URL.

Step 4: Update SSO group mappings to match any configured Okta groups (if applicable)

If you created user groups in Okta, update your SSO group mappings in runZero to map each Okta group to a runZero user group. Your users then get the right access and permissions when they sign in to runZero.

Updated