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 OIDC SSO with Okta

Configure Okta as your GraphOS organization's identity provider


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

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

Migration notes

⚠️ 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 configuration will no longer work, and your organization will lose access to GraphOS if you haven't created a new configuration.

To migrate from a legacy configuration, a GraphOS Org Admin must create a new SSO configuration. You can create a new configuration while the legacy configuration continues to provide SSO for your organization.

The GraphOS setup wizard takes you through the configuration process, step-by-step. It won't let you activate your new configuration until it has confirmed that you're able to sign in with it.

SSO Setup Wizard showing the verification step in GraphOS Studio

Once the new configuration is verified and active, you should remove any legacy configurations from your IdP.

Prerequisites

Setup requires:

  • An Okta user account with administrator privileges
  • A GraphOS user account with the Org Admin role

Setup

OIDC-based SSO setup has these steps:

  1. Enter your SSO details in GraphOS Studio.
  2. Create a custom Okta app integration for GraphOS.
  3. Verify and configure OIDC details.
  4. Verify your SSO configuration works.
  5. 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 OIDC as the SSO type. Click Continue.

Step 2. Create a custom Okta app integration

  1. Once you reach Step 2: Configure Your IdP in the wizard, open your Okta Administrator Dashboard in a separate browser tab.

  2. In your Okta Administrator Dashboard, go to the Applications view and click Create App Integration.

    NOTE

    To use the latest version of Apollo's SSO, ensure you create a custom app integration in Okta rather than use the GraphOS app in the Okta Application Network.

  3. In the dialog that appears, select OIDC - OpenID Connect as your sign-in method. For the Application type, select Web Application. Click Next.

    Okta custom app creation
  4. In the General Settings section, provide the following values:

    Leave the other (for example, Proof of possession, Grant type) as the default values.

  5. Add the following URIs:

  • In the Sign-in redirect URIs section, add the Sign-in URL provided in the GraphOS wizard.
  • In the Sign-out redirect URIs section, add https://studio.apollographql.com.
  • Leave the Base URIs section empty.
  1. For Assignments, you can select Skip group assignment for now or assign the users you want to have access to GraphOS. Click Save. This creates your custom app integration and brings you to its General tab.

  2. In the Client Credentials section of the General tab, copy the Client ID and paste it into the Client ID input in the GraphOS wizard. Do the same for the secret in the Client Secrets section.

  3. In Okta, while still on the app's General tab scroll to General Settings and click Edit. and scroll to the Login section. Add https://studio.apollographql.com/sso/login as the Initiate login URI. Click Save.

  4. In Okta, open the Sign On tab. Scroll to the OpenID Connect ID Token section and click Edit. Change the Issuer to be Okta URL and click Save. Copy the URL into the Issuer input in the GraphOS Wizard.

  5. In the setup wizard in GraphOS Studio, optionally enter a Discovery URL. Click Next.

Step 3. Configure OIDC

  1. In Okta, go back to the General tab of your custom app integration and confirm that the Sign-in redirect URIs contains the URL provided in the wizard.
  2. You don't need to make any claims configurations, since by default, custom OIDC apps in Okta include all user attributes on the app profile.
  3. Click Next.

Step 4. 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 5. 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 custom app integration in Okta.

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

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 integration. Then, click the Assignments tab.

    GraphOS Studio Okta integration assignment settings
  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.

Previous
Generic SAML Setup
Next
Microsoft Entra ID
Rate articleRateEdit on GitHubEditForumsDiscord

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

Privacy Policy

Company