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

Prerequisites

Setup requires:

• A GraphOS user account with the Org Admin role

  • Check the Members tab in GraphOS Studio to see your role and which team members are org admins

• Administrative access to your IdP

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.

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

Step 5. Enable SSO

Once you've verified your new SSO configuration works, you'll be prompted to finalize your configuration.

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.

Set default GraphOS role

Once you've enabled SSO, you can optionally set the default GraphOS role for new users logging in via SSO. If you don't set a default, the default role is Consumer. To update the default role for new SSO users, go to Settings > Security > Single sign-on and click Update new user role. Org admins can always update other users' roles.

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.