Set up SAML SSO with Okta

This guide walks through configuring Okta as your GraphOS organization's identity provider (IdP) for SAML-based SSO. Once you've set up your integration, you need to assign users to it in Okta so they can access GraphOS Studio via SSO.

If you're migrating your SSO configuration, see the self-service instructions .

Setup

SAML-based SSO setup has two main steps:

1. Create a custom Okta app integration for Apollo GraphOS.

2. Send your Okta app integration's SAML metadata to Apollo.

Setup requires an Okta account with administrator privileges.

Step 1. Create a custom app integration

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

1. From your Okta Administrator Dashboard, go to the Applications view. Click Create App Integration.

2. In the dialog that appears, select SAML 2.0 as your sign-in method. Click Next.

3. The Create SAML Integration dialog appears. In the General Settings step, provide the following values:

   • App integration name: Apollo GraphOS

   • Logo: Apollo logo (optional)

   

   Then click Next.

4. In the Configure SAML step, provide the following values:

   • Single sign on URL: Single sign-on URL provided by Apollo

     • Also check Use this for Recipient URL and Destination URL.

   • Audience URI (SP Entity ID): Entity ID provided by Apollo

   • Leave the default values for other settings, including leaving the RelayState blank.

5. Still in the Configure SAML step, scroll down to Attribute Statements. Set values for the following 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

   

   Then click Next.

6. In the Feedback step, select I'm an Okta customer adding an internal app. Click Finish.

Step 2. Send SAML metadata to Apollo

1. In your new Okta SAML integration, go to the Sign On > Settings > SAML 2.0 > Metadata details section.

   

2. Copy and paste the contents of the Metadata URL text box into a text file.

3. Send the Metadata URL to your Apollo contact. They will complete your SSO setup.

Once your SSO setup is finalized, you need to assign users to your custom app in Okta.

Assign users in Okta

Once your SSO is set up, you need to assign users to it so they can access GraphOS. You can assign individual users or groups by following these steps:

1. From your Okta Administrator Dashboard, open the Applications view from the left menu and open the Apollo GraphOS integration. Then, click the Assignments tab.

   

2. Click the Assign drop-down and then Assign to People or Assign to Groups.

3. Click Assign on the right of the people or group(s) you want to have access to your GraphOS Studio Org. Click Done.

Repeat these steps whenever you want to grant GraphOS Studio access to a new user or group. Okta displays every user and group you've assigned to the integration in the Assignments tab.

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 as expected, remove any legacy Apollo integrations in Okta if you have them.

Legacy setup

Click to see legacy instructions

With PingOne—Apollo's former SSO system—you could use Okta's GraphOS integration (now deprecated) or create a custom SAML integration.

Using Okta's Apollo GraphOS integration (deprecated)

Supported features

The Okta Apollo GraphOS SAML integration supports the following features:

• Just-In-Time (JIT) Provisioning
• Service provider-initiated (SP-initiated) SSO

An SP-initiated flow occurs when an end user signs in to an application directly from that application's sign-in page. For example, https://studio.apollographql.com/login is the sign-in location for GraphOS Studio. The integration supports users signing in from this page using SSO.You can use Okta's Bookmark App integration to simulate an Identity Provider-initiated (IdP-initiated) flow to allow users to sign in from Okta.

Configuration

1. From your Okta Administrator Dashboard, open the Applications view from the left menu. Click Browse App Catalog.
2. Search for "Apollo GraphOS." When “Apollo GraphOS Enterprise” appears, click + Add integration.
3. In the General Settings tab that opens, select Do not display application icon to users. (You'll set up a Bookmark App instead.) You can optionally change the Application label or keep the default "Apollo GraphOS Enterprise" label. Click Done.
4. The Assignments tab opens—you'll return to it later to assign users to the integration. For now, open the Sign On tab and copy the Metadata URL under Metadata details.

1. Send the following information to your Apollo contact:

• Metadata URL you copied in the last step
• Email address you use to log in to GraphOS Studio
  • The member associated with this email address will need an org admin role . You can begin SSO setup without it, but Apollo will update the role, if necessary, to complete setup.

Your Apollo contact will let you know once SSO setup is complete.

Using a custom integration (legacy)

Beginning in April 2024, Apollo recommends using the updated instructions for creating a custom integration provided above. You can refer to the instructions below if you need them for a previously created custom integration.

Step 1. Create an app integration

1. From your Okta Administrator Dashboard, navigate to the Applications view.
2. Click Create App Integration. The following dialog appears:
3. Select SAML 2.0 as your sign-in method.
4. Click Next. The Create SAML Integration dialog appears.

Step 2. Create a new SAML integration

The Create SAML Integration dialog includes multiple steps:

1. In the General Settings step, provide the following values:
   • App name: Apollo GraphOS
   • App logo: Apollo logo (optional)
   Then click Next.
2. In the Configure SAML step, provide the following values:
   • Single sign on URL: https://sso.connect.pingidentity.com/sso/sp/ACS.saml2
     • Also check Use this for Recipient URL and Destination URL.
   • Audience URI (SP Entity ID): PingConnect
     ⓘ note

     If PingConnect already exists, use fd76e619-6c0a-461c-912d-418278929d60
   • Default RelayState: https://pingone.com/1.0/fd76e619-6c0a-461c-912d-418278929d60
   
3. Still in the Configure SAML step, scroll down to Attribute Statements. Set values for the following 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
   Then click Next.
4. In the Feedback step, provide the following values:
   • Select I'm an Okta customer adding an internal app.
   Then click Finish.

Step 3. Send SAML metadata to Apollo

1. From your new SAML integration's details page, scroll down and click View SAML setup instructions on the right side.
2. In the dialog that appears, copy and paste the contents of the IDP metadata text box into a text file:
3. Send the text file to your Apollo contact. They will complete your SSO setup.

Add Apollo GraphOS as a Bookmark App

Since both legacy Okta integrations only support an SP-initiated flow , we strongly recommend hiding the application in the Okta catalog for users and instead adding Apollo GraphOS as a Bookmark App . Bookmark Apps allow your users to correctly launch the application from the Okta catalog.To do so, follow Okta's instructions with the following Bookmark Application configurations:

• Application label: Apollo GraphOS Enterprise
• URL: https://studio.apollographql.com/login