Self-Service SAML SSO with Microsoft Entra ID (formerly Azure AD)

Configure Entra ID as your GraphOS organization's identity provider


Self-service single sign-on (SSO) is only available for organizations with Dedicated and Enterprise plans who previously set up their SSO using PingOne and need to migrate. If you're unsure if you need to migrate please see the Migration Guide . If you are setting up SSO for the first time, please refer to these instructions .

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.

 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.
💡 tip
If your organization's SSO was set up before April 2024 according to the legacy instructions , Apollo highly recommends creating a new SSO configuration with the updated instructions .

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

SAML-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. Share your Entra ID enterprise application's SAML metadata in GraphOS Studio.
  4. Verify and configure OIDC details.
  5. Verify your SSO configuration works.
  6. 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 SAML as the SSO type. Click Continue.

Step 2. Create an Entra ID enterprise application

  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. Go to Identity > Applications > Enterprise applications and select +New application in the top menu.

  3. In the top menu, select +Create your own application.

  4. 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.

    Application creation in Microsoft Entra ID
  5. On the app's Overview page, select 2. Set up single sign-on. You'll assign users and groups later.

  6. On the app's Single sign-on page, select SAML as the single sign-on method.

  7. At the top of the SAML-based Sign-on page, click Upload metadata file and upload the file provided by the GraphOS setup wizard. Alternatively, you can enter these values manually in the Basic SAML Configuration section:

    • Identifier (Entity ID): Entity ID value provided by the setup wizard

    • Reply URL (Assertion Consumer Service URL): Single Sign-on URL provided by the setup wizard

    Click Save.

  8. 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.

    Application creation in Microsoft Entra ID

    Claims do not need a Namespace.

    Application creation in Microsoft Entra ID
  9. Under SAML Certificates, copy the App Federation Metadata URL into a text file for the next step.

Application creation in Microsoft Entra ID
  1. In the setup wizard in GraphOS Studio, select whether your Entra implementation requires signing an AuthnRequest.

  2. Click Next.

Step 3. Share SAML metadata with Apollo

In the setup wizard, enter the App Federation Metadata URL you previously copied into the Upload metadata from URL field. Click Next.

Step 4. Verify details

The GraphOS Studio setup wizard populates your SSO metadata based on the URL you entered in the last step. Verify the values are correct.

You can find them in Entra ID, Identity > Applications > Enterprise applications, in the application you created for GraphOS.

  • Your application's Entity ID is in the Single sign-on tab. Scroll down to the Basic SAML Configuration section and look for a field labeled Identifier (Entity ID). This field contains the Entity ID. It has the following format: urn:<unique>.<region>.auth0.com.

  • The SSO URL is also in thee Basic SAML Configuration section in the Sign on URL field.

Once you've verified the values or corrected them, click Next.

Step 5. 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 6. Enable SSO

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.

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.

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.

Legacy setup

⚠️ caution
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.If you previously configured SSO using the instructions below and want to use multi-organization SSO you must create a new SSO connection with the updated instructions.
Click to see legacy instructions
 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.

1. Create an Azure AD app registration

  1. Go to your Azure Portal and then navigate to Azure Active Directory.
  2. In the left pane, select App Registrations. Then in the top ribbon click + New Registration.
  3. On the Register an application page, provide the following information:
    • Provide a friendly name for the PingOne client (such as Apollo GraphOS or PingOneConnect).
    • Under Supported account types, select which Microsoft account types will have access.
    • Leave Redirect URI empty. You'll provide this information later.
    Azure App RegistrationThen click Register.

2. Retrieve your endpoint URL and client ID

  1. From the Overview section of your newly created app registration, copy and paste your Application (client) ID into a local text file.
  2. Still in the Overview section, select Endpoints from the top menu.
  3. Copy and paste the OpenID Connect metadata document URL into the same local text file:Azure endpoint URL and client ID

3. Create a client secret

  1. From the Certificates & secrets section of your app registration, click + New client secret and create a new secret.
  2. Copy and paste the secret's Value field to the same text file you created earlier:Azure client secret

4. Configure API permissions

  1. From the API permissions section of your app registration, check whether User.Read is listed by default. If isn't, add it manually:
    1. Select + Add a permission > Microsoft Graph > Application permissions.
    2. Search for Group, expand, and select Group.Read.All.
    3. Save your changes.
    4. If User.Read was not auto created, repeat this process for User.Read.
  2. 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.Azure configure API permissions
  3. 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.
  4. Save your changes.Azure manifest

5. Integrate PingOne with Azure AD

  1. After you receive your PingOne SSO invitation email, click the enrollment link to create a new account or sign in with an existing account.
  2. On the landing page, click Setup on the top ribbon.
  3. Select Connect to an Identity Repository > Microsoft Azure AD and click Next.
  4. From the Configure Your Microsoft Azure Connection modal:
    1. Copy and paste the endpoint URL, client ID, and client secret values saved earlier from Azure AD.
    2. Select Verify. PingOne will verify that it can query the endpoint(s) you've specified.
    3. For Scope, select the OAuth scopes to include in authentication requests.
    4. Click Next.
    Azure PingOne connection
  5. 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.
    Azure PingOne redirect URI
  6. 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.
  7. 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.
  8. Click Save to finish connecting Azure AD to PingOne.

6. Configure the OIDC application

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.
  1. 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.
    PingOne OIDC application
  2. In Step 1 of the Add OIDC Application wizard, configure the application name, description, category, and icon (optional).
  3. Click Next for Steps 2-5 (these are configured by default).
  4. 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.
  5. In Step 7 of the wizard (Group Access), select whichever groups should receive SSO access to Apollo.
  6. Click Done to complete the configuration.

7. Notify Apollo

After you complete the steps above, reach out to your Apollo contact. They will complete your SSO setup.