Self-Service OIDC SSO with Okta

This guide walks through configuring Okta as your GraphOS 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 GraphOS Studio via SSO.

Migration notes

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.

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.

   

4. In the General Settings section, provide the following values:

   • App integration name: Apollo GraphOS
   • Logo: Apollo logo (optional)

   Leave the other fields (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.

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

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

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

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

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

Step 5. Enable SSO

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.