Setting up Azure AD SSO

Superusers can configure single sign-on to the runZero Console using an external identity provider (IdP), which enables authentication and user access control to the runZero Console from your single sign-on (SSO) solution. By default, runZero has SSO functionality available, but it’s not a requirement to log in to the console. You can make it a requirement or disable it completely.

Here are the high-level steps to set up SSO using Azure AD to authenticate and manage user access to runZero:

  1. Add and configure runZero as an Azure AD app.
  2. Download the SSO configuration metadata in XML format.
  3. Set up SSO in runZero.
  4. Add users to your runZero app in Azure AD.

Requirements

Before you can set up SSO for Azure AD:

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

Step 1: Add and configure runZero as an Azure app

The first thing you need to do is add runZero as a non-gallery application to your Azure AD setup and to configure the settings for runZero as an Azure AD application.

  1. In Azure, go to Enterprise Applications > New Application > Create your own application.
  2. Under the What are you looking to do with your application? section, choose the Non-gallery application option.
  3. Name your application something like runZero, and then add it.
  4. Go to Azure Active Directory > Enterprise applications and open the newly created runZero application.
  5. Select the Single sign-on tab, and then choose SAML as the sign-on method.
  6. For the fields on the Configure App Settings page, go to https://console.runzero.com/team/sso/sp and copy the necessary service provider details:
    • Entity ID
    • Single sign-on URL
    • SSO callback (ACS) URL
  7. Enter the values into the relevant fields in the Azure AD portal.
  8. Do not set a value for “Sign on URL (Optional)” or “Relay State (Optional)”.

Step 2: Download the SSO configuration metadata

While editing your application settings, you can get the download link to obtain the SSO configuration metadata in XML. You’ll need this information to set up SSO in runZero.

  1. On the Configure App Settings page, find the SAML Signing Certificate section.
  2. Locate the XML download link under the Federation Metadata URL.
  3. Download the file. You’ll need the contents of this file for the next step.

Step 3: Set up Azure AD SSO in runZero

Now that you have the SSO configuration metadata in XML, you can configure Azure AD SSO settings in runZero.

  1. Go to https://console.runzero.com/team/sso/idp to access the SSO IdP provider settings page in runZero.
  2. Choose one of the following modes to enable SSO:
    • Allowed - Enables SSO, but users still have the option to login without SSO.
    • Required - Requires users to log in with SSO. Only superusers can log in without SSO.
  3. Enter the domain name that is associated with SSO authentication. This is likely your company domain (companyabc.com).
  4. Choose a default role for SSO users. This is the role all new users will be assigned when their account is created.
  5. Copy the XML you downloaded from Azure and paste it into the Metadata XML field on the runZero SSO IdP page.
  6. Apply your SSO settings. The remaining IdP fields will auto-configure for you.
    • The issuer URL will look something like https://sts.windows.net/00000000-0000-0000-0000-000000000000/ where the UUID at the end is your unique Microsoft Active Directory (tenant) ID, listed under App registrations > Overview > Endpoints.
    • The login URL will be something like https://login.microsoftonline.com/00000000-0000-0000-0000-000000000000/saml2 with the zero UUID replaced with your unique tenant ID.
    • The certificate will be Microsoft’s PEM encoded certificate, which will be extracted automatically from the XML.
    • On the Microsoft side, the redirection URL for runZero should be https://console.runzero.com/auth/<domain>/saml20/process, where <domain> is replaced with the domain specified in the runZero SSO settings.

Step 4: Add users to the runZero app in Azure

Now that you’ve completed the set up, you can go to the runZero app in Azure portal to add users and assign their access. Any users you add to the runZero app will be viewable from the Team members page in runZero, once they have logged into runZero.

Step 5: Update SSO group mappings to match any configured Azure groups (if applicable)

If you have created user groups within Azure, you will need to update your SSO group mappings in runZero to associate the groups created in Azure with user groups in runZero. This will ensure that the appropriate access and permissions are added to your users when they log in to runZero.

When setting up the SSO group mappings, note that the SSO attribute field must match the claim name from Azure AD.

Updated
Previous: Managing SSO group mappings Next: Setting up Okta SSO