Set up OIDC SSO with Microsoft Entra ID (formerly Azure AD)
Configure Entra ID as your GraphOS organization's identity provider
Single sign-on (SSO) is available only for Dedicated and Enterprise plans. This feature is not available as part of an Enterprise trial.
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.
If you're migrating your SSO configuration, see the self-service instructions.
ⓘ NOTE
For organizations using SSO, access to GraphOS is exclusively managed through your IdP. Any invitation links created before SSO setup will be automatically revoked and you won't be able to create new invitation links once SSO is enabled. To give team members access, assign them to the GraphOS application in your IdP.
Setup
ⓘ NOTE
Only GraphOS org admins can configure SSO. Check the Members tab in GraphOS Studio to see your role and which team members are org admins.
OIDC-based SSO setup in Entra ID has these steps:
- Create an app registration for Apollo GraphOS in Entra ID.
- Retrieve your Entra client ID, client secret, and issuer.
- Configure API permissions in Entra ID.
- Send your Entra ID's app registration's OIDC metadata to Apollo.
Setup requires at least a Cloud Application Administrator role.
Step 1. Create an Entra ID app registration
Send a request to your Apollo contact to configure an OIDC SSO integration. Include the organization name(s) you are setting up SSO for and the email domains you want to associate with the organization. Your Apollo contact will respond with:
- A redirect URI
- A link to a form where you can submit your SSO information to Apollo. You'll use this form in the last setup step.
ⓘ NOTE
The redirect URI differs for each GraphOS organization. If setting up SSO for multiple organizations, repeat the following steps for each organization using different values.
Go to your Microsoft Entra admin center. Alternatively, you can sign in to the Azure Portal and then go to Microsoft Entra ID.
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.
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 your Apollo contact.
- Enter a descriptive name for your application, such as
Click Register.
Step 2. Retrieve app registration data
- From the Overview section of your newly created app registration, copy and paste your Application (client) ID into a local text file.
- Next to Client credentials, click Add a certificate or secret and create a new secret.
- Copy and paste the secret's Value to the text file you created earlier.
- Back in the Overview section, select Endpoints from the top menu.
- Copy and open the OpenID Connect metadata document URL in a new browser tab. Find the
issuer
value. It should be formatted likehttps://login.microsoftonline.com/unique-value/vx.x
. Copy and paste this URL into your text file.
Step 3. Configure API permissions
From the API permissions section of your app registration, check whether
User.Read
is listed by default. If it isn't, add it manually:- Select + Add a permission > Microsoft Graph > Application permissions.
- Search for
User
, expand, and selectUser.Read.All
. Click Add permissions. - Save your changes.
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.
From the Manifest section of your app registration, find the
groupMembershipClaims
property. Change its value fromnull
to either"All"
or"SecurityGroup"
. These values ensure that the access token includes the group membership claim during SSO.Save your changes.
Step 4. Send OIDC metadata to Apollo
To complete the configuration, complete the Apollo-provided link provided in step 1 with the appropriate information:
- Client ID: the Application (client) ID you copied
- Client Secret: the secret value you copied
- Apollo encrypts this value and stores it securely.
- Issuer: the issuer value you copied from the OpenID Connect metadata document
- Discovery URL: you don't need to enter this since the OpenID Connect metadata document URL follows the standard
/.well-known/openid-configuration
format
Once submitted, inform your Apollo contact. They will then be able to complete your SSO setup.
Once your SSO setup is finalized, you need to assign users to your GraphOS app in Entra.
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.
![SSO testing in Microsoft Entra ID](/docs/f26459fb2b8ed291c1412b05da4877aa/entra-sso-test.jpg)
Once you've successfully tested your own user's ability to use SSO, add any applicable users or groups. Repeat these steps whenever you want to grant GraphOS Studio access to a new user or group.
Legacy setup
ⓘ NOTE
The below instructions are provided for reference only. Beginning in April 2024, Apollo recommends that all organizations use the updated instructions to create a new SSO connection.
To use multi-organization SSO, your SSO connection cannot use PingOne as shown in the legacy instructions below. Follow the updated instructions to create a new SSO connection.