Set up OIDC SSO with Microsoft Entra ID (formerly Azure AD)

This guide walks through configuring Microsoft Entra ID (formerly known as Azure Active Directory) as your GraphOS organization's identity provider (IdP) for OIDC-based SSO.

Prerequisites

Setup requires:

• A GraphOS user account with the Org Admin role

  • Check the Members tab in GraphOS Studio to see your role and which team members are org admins

• Administrative access to your IdP

Setup

OIDC-based SSO setup has these steps:

1. Enter your SSO details in GraphOS Studio.
2. Create a custom Entra ID enterprise application for GraphOS.
3. Verify and configure OIDC details.
4. Verify your SSO configuration works.
5. Enable SSO in GraphOS Studio.

The SSO setup wizard in GraphOS Studio guides you through these steps.

Step 1. Enter your SSO details

1. Go to GraphOS Studio. Open the Settings page from the top navigation. Open the Security tab from the left sidebar and click Migrate SSO. A setup wizard appears.
2. Enter the Email domain(s) you are setting SSO up for. Click Continue.
3. Select OIDC as the SSO type. Click Continue.

Step 2. Create an Entra ID app registration

1. Once you reach Step 2: Configure Your IdP in the wizard, go to your Microsoft Entra admin center. Alternatively, you can sign in to the Azure Portal and then go to Microsoft Entra ID.

2. In Entra, go to Identity > Applications > App registrations. If accessing Entra from the Azure Portal, go to Manage > App registrations. Select +New registration in the top menu.

3. On the Register an application page, provide the following information:

   • Enter a descriptive name for your application, such as Apollo GraphOS.

   • Under Supported account types, select which Microsoft account types should have access to GraphOS.

   • For Redirect URI, select Web and enter the redirect URI provided by the setup wizard.

4. Click Register.

5. From the Overview section of your newly created app registration, copy and paste your Application (client) ID into the Client ID field in the setup wizard.

6. Next to Client credentials, click Add a certificate or secret and create a new secret.

7. Copy and paste the secret's Value into the Client Secret field in the setup wizard.

8. Back in the Overview section, select Endpoints from the top menu.

9. Copy and open the OpenID Connect metadata document URL in a new browser tab. Find the issuer value. It should be formatted like https://login.microsoftonline.com/unique-value/vx.x. Copy and paste this URL into the Issuer field in the setup wizard.

10. Click Continue.

Step 3. Configure API permissions

1. From the API permissions section of your app registration, check whether User.Read is listed by default. If it isn't, add it manually:

   1. Select + Add a permission > Microsoft Graph > Application permissions.

   2. Search for User, expand, and select User.Read.All. Click Add permissions.

   3. Save your changes.

2. Also from the API Permissions section, select Grant admin consent for Default Directory next to the + Add a permission button. Doing this ensures that your users don't need to grant consent during SSO.

3. From the Manifest section of your app registration, find the groupMembershipClaims property. Change its value from null to either "All" or "SecurityGroup". These values ensure that the access token includes the group membership claim during SSO.

4. Save your changes.

Step 4. Verify SSO Configuration

To verify that your SSO configuration works, click Login with new SSO in the GraphOS Studio wizard. This button launches a new login session in a new browser tab. Once you successfully login using your new configuration, click Next.

Step 5. Enable SSO

Once you've verified your new SSO configuration works, you'll be prompted to finalize your configuration.

If team members could previously login before you implemented SSO, they must re-login to GraphOS Studio via SSO. Signing in creates a new user profile for them. Any personal API keys associated with their previous user profile will be lost. (Graph API keys are unaffected and remain functional.) Additionally, you must reassign any GraphOS roles associated with their previous user profile.

Set default GraphOS role

Once you've enabled SSO, you can optionally set the default GraphOS role for new users logging in via SSO. If you don't set a default, the default role is Consumer. To update the default role for new SSO users, go to Settings > Security > Single sign-on and click Update new user role. Org admins can always update other users' roles.

Assign users in Entra ID

Once you've set up your Apollo GraphOS application in Entra ID, you need to assign users to it so they can access GraphOS. You can assign individual users or groups from the User and groups page of your Apollo GraphOS application in Entra ID.

You may want to begin by adding yourself individually and then testing SSO by clicking Test at the bottom of the Single sign-on page. Once you've successfully tested your own user's ability to use SSO, add any applicable users or groups.

Once you've verified your new SSO configuration works, you'll be prompted to finalize your configuration.

If team members could previously login before you implemented SSO, they must re-login to GraphOS Studio via SSO. Signing in creates a new user profile for them. Any personal API keys associated with their previous user profile will be lost. (Graph API keys are unaffected and remain functional.) Additionally, you must reassign any GraphOS roles associated with their previous user profile.

Once you've confirmed the new configuration works for your users, remove any legacy Apollo GraphOS applications in Entra ID or app registrations in Azure AD if you have them.