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.

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

SAML-based SSO setup has these steps:

1. Enter your SSO details in GraphOS Studio.
2. Create a custom Okta app integration for GraphOS.
3. Share your Okta app integration's SAML metadata in GraphOS Studio.
4. Verify and configure OIDC details.
5. Verify your SSO configuration works.
6. 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 SAML 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 SAML 2.0 as your sign-in method. Click Next.

   

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

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

   • Single sign on URL: Single sign-on URL provided by the setup wizard

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

   • Audience URI (SP Entity ID): Entity ID provided by the setup wizard

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

6. Still in the Configure SAML step, scroll down to Attribute Statements. Set values for the following attributes:

   • sub: user.email

   • email: user.email

   • given_name: user.firstName

   • family_name: user.lastName

   Leave the Name format as Unspecified.

   

   Then click Next.

7. In the Help Okta Support understand how you configured this application step, select I'm an Okta customer adding an internal app. Click Finish.

8. In the setup wizard in GraphOS Studio, select whether your Okta implementation requires signing an AuthnRequest.

9. Click Next.

Step 3. Share SSO metadata with Apollo

1. In your Okta Administrator Dashboard, go to the Sign On > Settings > SAML 2.0 > Metadata details section in the app integration you just created.

   

2. Copy and paste the contents of the Metadata URL text box into the setup wizard in GraphOS Studio. Once the wizard shows the green success banner that says Successfully parsed SAML metadata, click Next.

Step 4. Verify details

The GraphOS Studio setup wizard populates your SSO metadata based on the URL you entered in the last step. Verify the values are correct.

You can find your EntityID and SSO URL in your Okta Administrator Dashboard in the app integration you created for GraphOS.

• Your app integration's Entity ID is in the Sign On tab. Scroll down to the SAML 2.0 section and look for a field labeled Issuer. (You may need to click More details to see it.) This field contains the Entity ID. It uses a URL format: http://www.okta.com/<unique-id>.

• The SSO URL is also in the SAML 2.0 section in a field labeled Sign on URL.

Once you've verified the values or corrected them, click Next.

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