Set up SAML SSO with Okta
Configure Okta as your GraphOS organization's identity provider
Single sign-on (SSO) is available only for Dedicated and Enterprise plans. This feature is not available as part of an Enterprise trial.
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.
If you're migrating your SSO configuration, see the self-service instructions.
ⓘ NOTE
For organizations using SSO, access to GraphOS is exclusively managed through your IdP. Any invitation links created before SSO setup will be automatically revoked and you won't be able to create new invitation links once SSO is enabled. To give team members access, assign them to the GraphOS application in your IdP.
Setup
ⓘ NOTE
Only GraphOS org admins can configure SSO. Check the Members tab in GraphOS Studio to see your role and which team members are org admins.
SAML-based SSO setup has two main steps:
- Create a custom Okta app integration for Apollo GraphOS.
- Send your Okta app integration's SAML metadata to Apollo.
Setup requires an Okta account with administrator privileges.
Step 1. Create a custom app integration
ⓘ NOTE
To use the latest version of Apollo's SSO, ensure you are creating a custom app integration in Okta rather than using the GraphOS app in the Okta Application Network.
Send a request to your Apollo contact for Apollo's service provider (SP) SAML information. Include the organization name(s) you are setting SSO up for.
Your Apollo contact will respond with a URL where you can download Apollo's SP SAML XML metadata file(s) for your organization(s). This file contains the following values:
- Single Sign-on URL
- Entity ID
ⓘ NOTE
SSO metadata values differ for each GraphOS organization. If setting up SSO for multiple organizations, repeat the following steps for each organization using different values.
From your Okta Administrator Dashboard, go to the Applications view. Click Create App Integration.
In the dialog that appears, select SAML 2.0 as your sign-in method. Click Next.
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.
- App integration name:
In the Configure SAML step, provide the following values:
- Single sign on URL: Single sign-on URL provided by Apollo
- Also check Use this for Recipient URL and Destination URL.
- Audience URI (SP Entity ID): Entity ID provided by Apollo
- Leave the default values for other settings, including leaving the RelayState blank.
- Single sign on URL: Single sign-on URL provided by Apollo
Still in the Configure SAML step, scroll down to Attribute Statements. Set values for the following attributes:
sub:user.email- The
subattribute should uniquely identify any particular user to GraphOS. In most cases,user.emailprovides this unique mapping.
- The
email:user.emailgiven_name:user.firstNamefamily_name:user.lastName
Then click Next.
In the Feedback step, select I'm an Okta customer adding an internal app. Click Finish.
Step 2. Send SAML metadata to Apollo
In your new Okta SAML integration, go to the Sign On > Settings > SAML 2.0 > Metadata details section.
Copy and paste the contents of the Metadata URL text box into a text file.
Send the Metadata URL to your Apollo contact. They will complete your SSO setup.
Once your SSO setup is finalized, you need to assign users to your custom app in Okta.
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.
Once you've confirmed the new configuration works as expected, remove any legacy Apollo integrations in Okta if you have them.
Legacy setup
ⓘ NOTE
The below instructions are provided for reference only. Beginning in April 2024, Apollo recommends that all organizations use the updated instructions to create a new SSO connection.
To use multi-organization SSO, your SSO connection cannot use PingOne as shown in the legacy instructions below. Follow the updated instructions to create a new SSO connection.
