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.
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.
SAML-based SSO setup has two main steps:
- Create an enterprise application for Apollo GraphOS in Entra ID.
- Send your Entra ID's application's SAML metadata to Apollo.
Setup requires at least a Cloud Application Administrator role.
Step 1. Create an enterprise application
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 your Microsoft Entra admin center. Alternatively, you can sign in to the Azure Portal and then navigate to Microsoft Entra ID.
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.
![Application creation in Microsoft Entra ID](/docs/a85a3ce16fde452ba620c16e3384ed8b/entra-saml-certificates.jpg)
Step 2. Send SAML metadata to Apollo
Send your Apollo contact the App Federation Metadata URL you previously copied. 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.