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 Dedicated and Enterprise plans 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 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.
⚠️ 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 setup will no longer work, and your organization will lose access to GraphOS.
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:
- Enter your SSO details in GraphOS Studio.
- Create a custom Okta app integration for GraphOS.
- Verify and configure OIDC details.
- Verify your SSO configuration works.
- Enable SSO in GraphOS Studio.
The SSO setup wizard in GraphOS Studio guides you through these steps.
Step 1. Enter your SSO details
- 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.
- Enter the Email domain(s) you are setting SSO up for. Click Continue.
- Select OIDC as the SSO type. Click Continue.
Step 2. Create a custom Okta app integration
Once you reach Step 2: Configure Your IdP in the wizard, open your Okta Administrator Dashboard in a separate browser tab.
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.
In the dialog that appears, select OIDC - OpenID Connect as your sign-in method. For the Application type, select Web Application. Click Next.
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.
- App integration name:
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.
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.
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.
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/loginas the Initiate login URI. Click Save.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.
In the setup wizard in GraphOS Studio, optionally enter a Discovery URL. Click Next.
Step 3. Configure OIDC
- 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.
- 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.
- 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
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:
From your Okta Administrator Dashboard, open the Applications view from the left menu and open the Apollo GraphOS integration. Then, click the Assignments tab.
Click the Assign drop-down and then Assign to People or Assign to Groups.
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.