Self-Service SSO with an OIDC-based IdP
Configure an OIDC-based identity provider
This guide walks through configuring a generic OpenID Connect (OIDC) based identity provider (IdP) for use with Apollo SSO. If you use Okta or Microsoft Entra ID as your IdP, instead see the corresponding guide for your IdP:
Microsoft Entra ID (formerly known as Azure Active Directory)
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:
- Enter your SSO details in GraphOS Studio.
- Create a custom application for GraphOS in your IdP.
- 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 application
Once you reach Step 2: Configure Your IdP in the wizard, open your IdP's admin dashboard in a separate browser tab.
Create a new application in your SSO environment. While doing so, set the following values:
App Name:
Apollo GraphOS
Logo: Apollo logo (optional)
Retrieve the following values from your SSO provider and enter them in the setup wizard.
Client ID: this should be a specific Application ID
Client Secret: a secret value you may need to first create in your IdP
Issuer: the issuer value from a OpenID Connect metadata document found in your IdP
Step 3. Configure OIDC to work with Apollo
Verify that the Sign-in Redirect URL in your application matches the one shown in the GraphOS wizard.
If your IdP permits it, set the following user attributes:
sub
:user.email
The
sub
attribute should uniquely identify any particular user to GraphOS. In most cases,user.email
oruser.mail
provides this unique mapping.
email
: Your IdP's email attribute, often something likeuser.email
given_name
: Your IdP's first name attribute, often something likeuser.firstName
family_name
: Your IdP's last name attribute,often something likeuser.lastName
Save this configuration in your IdP and click Next in the GraphOS wizard.
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
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.
Assign users in your IdP
Once your SSO setup is live, assign users to your new Apollo GraphOS application in your IdP. Consult your IdP documentation if necessary. For help assigning the relevant groups and users, contact your SSO or Identity & Access Management team.