Set up SSO with an OIDC-based IdP

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:

• Okta

• Microsoft Entra ID (formerly known as Azure Active Directory)

Once you've set up your integration, you need to assign users to it in your IdP so they can access GraphOS Studio via SSO. Before assigning users, Apollo recommends setting a default GraphOS role for users logging in via SSO. You can also configure Okta to assign GraphOS roles to your users based on their Okta groups.

SSO impact on user accounts and access

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, you must assign them to the GraphOS application in your IdP.

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 application for GraphOS in your IdP.
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 Configure 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 application

1. Once you reach Step 2: Configure Your IdP in the wizard, open your IdP's admin dashboard in a separate browser tab.

2. Create a new application in your SSO environment. While doing so, set the following values:

   • App Name: Apollo GraphOS

   • Logo: Apollo logo (optional)

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

1. Verify that the Sign-in Redirect URL in your application matches the one shown in the GraphOS wizard.

2. 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 or user.mail provides this unique mapping.

• email: Your IdP's email attribute, often something like user.email

• given_name: Your IdP's first name attribute, often something like user.firstName

• family_name: Your IdP's last name attribute,often something like user.lastName

1. 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. You may need to assign yourself to the application in your IdP first.

Once you successfully login using your new configuration, click Continue.

Step 5. Enable SSO

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

You can set a default role for any users signing in with SSO. Apollo recommends setting the default role before assigning users.

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.

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.

Assign GraphOS roles in your IdP

Once you've set up SSO, each user assigned to your GraphOS integration has the GraphOS organization's default role. To avoid manually setting the appropriate role for each user, you can configure your IdP to set GraphOS roles based on the IdP groups they belong to.

With GraphOS automated role assignment, your IdP serves as the source of truth for GraphOS roles and permissions. You can assign GraphOS roles to users before they log into GraphOS Studio for the first time. Updates to user permissions in your IdP automatically propagate to GraphOS. This makes access control faster, more secure, and less error-prone.

How role assignment works

GraphOS supports the following role assignment mechanisms using OIDC claims:

• Setting organization-wide roles using the graphos_org_role attribute
• Setting graph-specific roles using the graphos_graph_roles attribute

If a user has both graphos_org_role and graphos_graph_roles attributes set, graph-specific roles override their organization-wide role. For example, suppose a user has the Observer organization-wide role. You can assign them the Contributor role for one graph they need extra access to and the Graph Admin role for another graph they should have administrative access to.

Setup

This setup relies on mapping your IdP groups to GraphOS roles. Apollo recommends this as the most straightforward way to assign GraphOS roles using your IdP, but your setup may differ based on your configuration.

Step 1: Add user attributes

1. In your IdP administrator dashboard, add one or both of the following attributes:

   • For organization-wide roles, add an attribute named graphos_org_role.

     The following string values are valid GraphOS organization-wide roles:

     • ORG_ADMIN

     • GRAPH_ADMIN

     • CONTRIBUTOR

     • DOCUMENTER

     • OBSERVER

     • CONSUMER

     • BILLING_MANAGER

   • For graph-specific roles, add an attribute named graphos_graph_roles. It takes an array of strings.

2. Still in your IdP, go to the GraphOS Studio application you created during SSO setup.

3. Add new attribute statements for the user attribute(s) you previously created. The names should be graphos_org_role or graphos_graph_roles.

4. Save your changes.

Step 2: Assign organization-wide GraphOS roles to groups

Follow these steps to assign organization-wide to groups.

1. Assign groups to your GraphOS Studio application if you haven't already done so.

2. Select the appropriate GraphOS Organization Role for each group.

3. If your IdP uses group prioritization, ensure the groups are ordered correctly. For example, in Okta, the groups with more privileged access should have a higher priority.

   • For example, imagine an Apollo Admins group has the highest priority. Suppose this group has the most privileges as Org admins.

   • Next, suppose the Feature Team 1 has the Graph Admin role.

   • The rest of the Engineering organization has the Contributor role.

   • This priority order ensures a user belonging to the Apollo Admin group has Org admin privileges, even if they also belong to Feature Team 1 and the Engineering groups. If a user only belongs to the Engineering group, they receive the Contributor role.

   Review your IdP's prioritization documentation to confirm the correct order.

Step 3: Assign graph-specific roles to individual users

Follow these steps to assign graph-specific roles to individuals or groups. If a user has both organization-wide and graph-specific roles set, the graph-specific roles take precedence.

1. In your IdP, go to where you assign individuals and groups access to your GraphOS Studio application.

2. Edit any individually assigned user or group and add as many graph-specific roles as necessary, using the <graph-id>:<graph-role> format for each graph-specific role.

   • A graph's ID is the portion of the graph ref before the @.

   • Valid values for graph-specific roles are GRAPH_ADMIN, CONTRIBUTOR, DOCUMENTER, OBSERVER, and CONSUMER.

   • Ensure the delimiter between the graph ID and role is a colon (:).

   • For example, docs-sandbox:DOCUMENTER is a valid string for assigning the Documenter role to a graph with the ID docs-sandbox.

Role assignment behavior

Once you've completed the previous steps, whenever a user signs into GraphOS, they receive the role based on their IdP groups and/or individual graph-specific roles. If they don't belong to an IdP group that was assigned a role, they receive the SSO default role.

If a user's assigned role changes in IdP while logged into GraphOS Studio, they must log out of Studio and back in to receive their new role and permissions.

Sending multiple roles

Each GraphOS team member can only have one organization-wide role. If your IdP sends multiple roles for a single user, GraphOS treats it as invalid. This should only be a concern if you incorrectly configured the graphos_org_role user attribute. If a user is part of multiple groups, IdPs generally only send the role corresponding to the highest priority group or last claim.

Team members can have as many graph-specific roles as graphs. Their graph-specific role must have higher permissions than their organization-wide role to be applied.

Sending invalid roles

Only the graphos_org_role values specified in setup Step 1 are valid. If your IdP sends an invalid graphos_org_role:

• Existing users keep their current roles.

• New users receive your organization's default role.

• Either way, the user will still be authenticated and allowed to log in.

Accidental removal of org admins

If your role assignment removes all org admins from your GraphOS organization, you can fix it by:

• Updating your assignments so that at least one group maps to the Org Admin role.

• Reaching out to support@apollographql.com to update roles manually.