Set up SAML 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 SAML-based SSO.
Send a request to your Apollo contact for Apollo's service provider (SP) SAML information. Include the organization name(s) you are setting SSO up for.
Your Apollo contact will respond with a URL where you can download Apollo's SP SAML XML metadata file(s) for your organization(s). This file contains the following values:
Single Sign-on URL
Entity ID
ⓘ NOTE
SSO metadata values differ for each GraphOS organization. If setting up SSO for multiple organizations, repeat the following steps for each organization using different values.
Go to Identity > Applications > Enterprise applications and select +New application in the top menu.
In the top menu, select +Create your own application.
Enter Apollo GraphOS as the name of your app. Below, keep the Integrate any other application you don't find in the gallery (Non-gallery) option selected. Click Create.
On the app's Overview page, select 2. Set up single sign-on. You'll assign users and groups later.
On the app's Single sign-on page, select SAML as the single sign-on method.
At the top of the SAML-based Sign-on page, click Upload metadata file and upload the file provided by your Apollo contact. Alternatively, you can enter these values manually in the Basic SAML Configuration section:
Identifier (Entity ID): Entity ID value provided by Apollo
Reply URL (Assertion Consumer Service URL): Single Sign-on URL provided by Apollo
Click Save.
In Attributes & Claims, ensure the following claim names have the corresponding source attributes:
email: user.mail
given_name: user.givenname
family_name: user.surname
sub: user.userprinicipalname
Otherwise, manually enter them.
Claims do not need a Namespace.
Under SAML Certificates, copy the App Federation Metadata URL into a text file for the next step.
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.
Repeat these steps whenever you want to grant GraphOS Studio access to a new user or group.
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.
ⓘ NOTE
These steps use PingOne's email invite method, because in some cases Apollo's legacy entity ID (PingConnect) might already be used by another application in your organization.
From the API permissions section of your app registration, check whether User.Read is listed by default. If isn't, add it manually:
Select + Add a permission > Microsoft Graph > Application permissions.
Search for Group, expand, and select Group.Read.All.
Save your changes.
If User.Read was not auto created, repeat this process for User.Read.
Also from the API Permissions section, select Grant admin consent 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 from null to either All or SecurityGroup.
This ensures that the group membership claim is included in the access token during SSO.
After you receive your PingOne SSO invitation email, click the enrollment link to create a new account or sign in with an existing account.
On the landing page, click Setup on the top ribbon.
Select Connect to an Identity Repository > Microsoft Azure AD and click Next.
From the Configure Your Microsoft Azure Connection modal:
Copy and paste the endpoint URL, client ID, and client secret values saved earlier from Azure AD.
Select Verify. PingOne will verify that it can query the endpoint(s) you've specified.
For Scope, select the OAuth scopes to include in authentication requests.
Click Next.
In Step 2 of the wizard, copy the PingOne Redirect URI and paste it on the Azure AD app registration.
Redirect URIs can be configured from the Overview section of your app registration under the Essentials menu in Azure AD.
Select Redirect URIs > Add a platform > Web and enter the Redirect URI you copied from PingOne. Select Configure to save changes.
Back on the PingOne configuration wizard, select Next after copying and pasting the URI.
In Step 3 of the wizard, configure the Map Attributes section by mapping the incoming attributes or claims from Azure AD to PingOne. You can leave this with the default Attribute Mapping.
In Step 4 of the wizard, choose whether or not to synchronize your user groups from Azure AD to your PingOne user groups.
The permissions User.Read and Group.Read.All are required for synchronization to be successful.
Any PingOne user groups that do not exist in your Azure provider will be replaced by the Azure groups.
Each of your Azure group members are automatically added to the corresponding PingOne groups when the user initially signs on (SSO) to PingOne. This is PingOne's just-in-time user provisioning.
Click Save to finish connecting Azure AD to PingOne.
After you successfully configure the identity bridge between Azure AD and PingOne, you need to configure and enable Apollo as an OIDC application. The configuration for this application should already be initialized, and you can access it via the Complete your Application Configuration reminder under Applications in the PingOne admin console.
Select Meteor Development Group - GraphOS Studio under Complete your Application Configuration.
ⓘ NOTE
If the Add OIDC Application wizard doesn't automatically pop-up, select the SAML tab and then select the OIDC tab.
In Step 1 of the Add OIDC Application wizard, configure the application name, description, category, and icon (optional).
Click Next for Steps 2-5 (these are configured by default).
In Step 6 of the wizard (Attribute Mapping), you must map email to email and sub to preferred_username. You can optionally map more attributes for given name, family name, and others.
In Step 7 of the wizard (Group Access), select whichever groups should receive SSO access to Apollo.
