Join us from October 8-10 in New York City to learn the latest tips, trends, and news about GraphQL Federation and API platform engineering.Join us for GraphQL Summit 2024 in NYC
Docs
Start for Free

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 and 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 organization's identity provider (IdP) for SAML-based SSO.

⚠️ CAUTION

If your organization's SSO was set up before April 2024, you must create a new SSO configuration with the updated instructions before November 15, 2024. After November 15, 2024, the legacy setup will no longer work, and your organization will lose access to GraphOS.

Prerequisites

Setup requires:

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 , 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 . 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 a new login session in a new browser tab. Once you successfully login using your new configuration, click Next.

Step 6. Enable SSO

In the setup wizard, click the Complete button to finalize setup.

Once you click Complete, all users will be logged out of your organization, and will need to sign in again from https://studio.apollographql.com/login using SSO. To give them access, ensure you've assigned them to your new enterprise application in Entra ID.

Once you've confirmed the new configuration works as expected, remove any legacy Apollo applications in Entra ID if you have them.

Assign users in Entra ID

Once you've set up your 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

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.

Previous
Okta
Next
Generic SAML Setup
Rate articleRateEdit on GitHubEditForumsDiscord

© 2024 Apollo Graph Inc., d/b/a Apollo GraphQL.

Privacy Policy

Company