Setting up Microsoft Entra SSO

View as Markdown

Superusers can configure single sign-on to the runZero Console through an external identity provider (IdP), so your single sign-on (SSO) solution handles authentication and user access control for the runZero Console. SSO is available by default but not required to sign in to the console. You can make it required or disable it completely.

The high-level steps to set up Microsoft Entra (formerly Azure AD) SSO for runZero:

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

Requirements

Before you set up SSO for the Microsoft Identity Platform:

  • 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

First, add runZero as a non-gallery application to your Azure AD setup and 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 add it.
  4. Go to Azure Active Directory > Enterprise applications and open the new runZero application.
  5. Select the Single sign-on tab and 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 service provider details:
    • Entity ID
    • Single sign-on URL
    • SSO callback (ACS) URL
  7. Enter the values in the matching fields in the Azure AD portal.
  8. Do not set a value for “Sign on URL (Optional)” or “Relay State (Optional)”.
  9. To use group information from Azure for group membership in runZero, configure the IdP to send group information.

Step 2: Download the SSO configuration metadata

While editing your application settings, download the SSO configuration metadata in XML. You need it 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. The next step uses its contents.

Step 3: Set up Entra ID SSO in runZero

With the metadata XML in hand, configure the Entra ID SSO settings in runZero.

  1. Go to https://console.runzero.com/team/sso/idp to open the SSO IdP provider settings page in runZero.
  2. Choose a mode to enable SSO:
    • Allowed enables SSO, but users can still sign in without it.
    • Required makes users sign in with SSO. Only superusers can sign in without SSO.
  3. Enter the domain name associated with SSO authentication. This is likely your company domain (companyabc.com).
  4. Choose a default role for SSO users. This is the role every new user gets 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 fill in automatically.
    • The issuer URL looks 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 sign-in URL looks something like https://login.microsoftonline.com/00000000-0000-0000-0000-000000000000/saml2, with the zero UUID replaced by your unique tenant ID.
    • The certificate is Microsoft’s PEM encoded certificate, 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 the domain specified in the runZero SSO settings.

Step 4: Add users to the runZero app in Azure

With setup complete, go to the runZero app in the Azure portal to add users and assign their access. Users you add to the runZero app appear on the Team members page in runZero once they have signed in.

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

If you created user groups within Azure, update your SSO group mappings in runZero to associate those Azure groups with runZero user groups. That way your users get the appropriate access and permissions when they sign in to runZero.

When you set up the SSO group mappings, the SSO attribute field must match the claim name from Entra ID.

Updated