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

Set up SSO with a SAML-based IdP

Configure a SAML-based 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 a generic SAML-based identity provider (IdP) for use with Apollo SSO. If you use Okta or Microsoft Entra ID as your IdP, instead see the corresponding guide for your IdP:

  • Okta
  • Microsoft Entra ID (formerly known as Azure Active Directory)

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

Setup

SAML-based SSO setup has two main steps:

  1. Create a custom application in your IdP.
  2. Send your application's SAML metadata to Apollo.

These steps generally require administrative access to your IdP.

Step 1. Create a custom application

  1. 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 organization. If setting up SSO for multiple organizations, repeat the following steps for each organization using different values.

  1. Create a new application in your SSO environment. While doing so, set the following values:

    • App Name: Apollo GraphOS
    • App logo: Apollo logo (optional)
  2. If your IdP permits it, upload the Apollo-provided SP SAML XML metadata file. Otherwise, open the XML metadata file, view the SAML metadata values, and manually enter them in your IdP.

    • Set your Single Sign-on URL or ACS URL to the Single Sign-on URL. You can also use this value for the following :

      • Recipient
      • ACS (Consumer) URL Validator
      • ACS (Consumer) URL
    • Set your Entity ID to the Entity ID value.

  3. Set the following user attributes:

    • sub: user.email
      • The sub attribute should uniquely identify any particular user to GraphOS. In most cases, user.email provides this unique mapping.
    • email: user.email
    • given_name: user.firstName
    • family_name: user.lastName
  4. Save your configuration.

Step 2. Send SAML metadata to Apollo

Send your Apollo contact your IdP SAML XML metadata file. If you can't send this file, send one of the following instead:

  • IdP entity ID
  • IdP single sign-on URL / SSO URL
  • IdP x509 certificate

Your Apollo contact will then be able to complete your SSO setup.

Once your SSO setup is live, assign users to your new Apollo GraphOS application in your IdP. For help assigning the relevant groups and users, contact your SSO or Identity & Access Management team.

If team members could previously login before you implemented SSO, they must re-login to 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 setup works as expected, remove any legacy Apollo GraphOS applications in your IdP.

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.

Previous
Microsoft Entra ID
Next
Microsoft Entra ID
Rate articleRateEdit on GitHubEditForumsDiscord

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

Privacy Policy

Company