Set up SAML SSO with Microsoft Entra ID (formerly Azure AD)

This guide walks through configuring Microsoft Entra ID (formerly known as Azure Active Directory) 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 Entra ID 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 Entra ID to assign GraphOS roles to your users based on their Entra ID 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

SAML-based SSO setup has these steps:

1. Enter your SSO details in GraphOS Studio.
2. Create a custom Entra ID enterprise application for GraphOS.
3. Share your Entra ID enterprise application's SAML metadata in GraphOS Studio.
4. Verify and configure SAML 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 Configure 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 an Entra ID enterprise application

1. Once you reach Step 2: Configure Your IdP in the wizard, go to your Microsoft Entra admin center. Alternatively, you can sign in to the Azure Portal and then go to Microsoft Entra ID.

2. Go to Identity > Applications > Enterprise applications and select +New application in the top menu.

3. In the top menu, select +Create your own application.

4. Enter Apollo GraphOS as the name of your app. Below, keep the Integrate any other application you don't find in the gallery (Non-gallery) option selected. Click Create.

   

5. On the app's Overview page, select 2. Set up single sign-on. You'll assign users and groups later.

6. On the app's Single sign-on page, select SAML as the single sign-on method.

7. At the top of the SAML-based Sign-on page, click Upload metadata file and upload the file provided by the GraphOS setup wizard. Alternatively, you can enter these values manually in the Basic SAML Configuration section:

   • Identifier (Entity ID): Entity ID value provided by the setup wizard

   • Reply URL (Assertion Consumer Service URL): Single Sign-on URL provided by the setup wizard

   Click Save.

8. In Attributes & Claims, ensure the following claim names have the corresponding source attributes:

   • email: user.mail

   • given_name: user.givenname

   • family_name: user.surname

   • sub: user.userprinicipalname

   • Unique User Identifier: user.userprinicipalname

   Otherwise, manually enter them.

   

   Leave Namespace blank for each claim.

   

9. Under SAML Certificates, copy the App Federation Metadata URL into a text file for the next step.

   

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

11. Click Continue.

Step 3. Share SAML metadata with Apollo

In the setup wizard, enter the App Federation Metadata URL you previously copied into the Upload metadata from URL field. 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 them in Entra ID, Identity > Applications > Enterprise applications, in the application you created for GraphOS.

• Your application's Entity ID is in the Single sign-on tab. Scroll down to the Basic SAML Configuration section and look for a field labeled Identifier (Entity ID). This field contains the Entity ID. It has the following format: urn:<unique>.<region>.auth0.com.

• The SSO URL is also in thee Basic SAML Configuration section in the Sign on URL field.

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

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

Step 6. 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 Entra ID

Once you've set up your Apollo GraphOS application in Entra ID, you need to assign users to it so they can access GraphOS. You can assign individual users or groups from the User and groups page of your Apollo GraphOS application in Entra ID.

You may want to begin by adding yourself individually and then testing SSO by clicking Test at the bottom of the Single sign-on page.

Once you've successfully tested your own user's ability to use SSO, add any applicable users or groups. Once you've confirmed the new configuration works for your users, remove any legacy Apollo GraphOS applications in Entra ID or app registrations in Azure AD if you have them.

Assign GraphOS roles in Entra ID

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 Entra ID to set GraphOS roles based on the Entra ID groups they belong to.

With GraphOS automated role assignment, Entra ID 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 Entra ID 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 SAML assertions:

• 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 Entra ID groups to GraphOS roles. Apollo recommends this as the most straightforward way to assign GraphOS roles using Entra ID, but your setup may differ based on your configuration.

Follow steps 1 and 2 to set organization-wide roles and step 3 for graph-specific roles.

Step 1: Add graphos_org_role claim

1. In your Microsoft Entra admin center, go to Identity > Applications > Enterprise applications and select the GraphOS application you previously created.

2. Go to the Single sign-on section and click Edit next to Attributes & Claims.

3. Click +Add new claim and give your new claim the name graphos_org_role. Leave the Namespace blank.

   

4. Expand the Claim conditions section. This is where you'll map groups to GraphOS roles.

   

   One claim condition row represents one GraphOS role and all the groups you want to assign to it. For each GraphOS role you want to map groups to, select the following:

   • User type: Members

   • Scoped Groups: Select all Entra ID groups that should have the same GraphOS role.

   • Source: Attribute

   • Value: Enter the GraphOS role name in all caps without quotes. EntraID inserts quotes for constant values..

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

     • ORG_ADMIN

     • GRAPH_ADMIN

     • CONTRIBUTOR

     • DOCUMENTER

     • OBSERVER

     • CONSUMER

     • BILLING_MANAGER

   The order of the rows matters. Since Entra ID assigns values based on the last condition met, you should assign groups to GraphOS roles in increasing order of permissions. This ensures that users who belongs to multiple groups get the highest level of permissions.

   • In the example above, imagine the general Engineering group is the Scoped Group for the CONTRIBUTOR role in the first claim condition.

   • Next, suppose a Feature Team 1 group has the GRAPH_ADMIN role.

   • Finally, an Apollo Admins group has the most privileges as ORG_ADMINs.

   • This order ensures a member of 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.

5. Save your changes.

Step 2: Include claim in manifest

1. Still in your Microsoft Entra admin center, go to Applications > App registrations > All applications and select the GraphOS application you added claims to.

2. In the App registration left nav, open Manage > Manifest. Set both isFallbackPublicClient and api.acceptMappedClaims to true

   

3. Click Save.

(Optional) Step 3: Set graph-specific roles

Use the following steps to set graphos_graph_roles attributes on individual users.

1. Find your Entra GraphOS application's ID for use in API calls. Note it down for use in the following steps. You can find your application ID either:

   • In the application's Manifest in the App Registrations view under id

     

   • Using a GET request to:

     url

     copy

     https://graph.microsoft.com/v1.0/applications?$select=id,displayName&$filter=displayName eq 'Apollo GraphOS'

     This assumes that your application's name is "Apollo GraphOS." If it isn't, change the portion after displayName eq to your application's name.

   note

   The ID you use in API calls is different from the Application ID on the application's Overview page. Ensure you use one of the methods above to get the correct ID.

2. Define the graphos_graph_roles extension and attach it to your Entra Apollo GraphOS application using a POST request to:

   url

   copy

   https://graph.microsoft.com/v1.0/applications/{application-id}/extensionProperties'

   With the following request body:

   JSON

   copy

   {
     "name": "graphos_graph_roles",
     "dataType": "String",
     "isMultiValued": true,
     "targetObjects": [
         "User"
     ]
   }

   See the example in the Graph Explorer below:

   POST https://graph.microsoft.com/v1.0/applications/8ec36bea-9fca-4aab-bacc-fb28d1bbb25d/extensionProperties

   

3. Confirm the extension was created using the following GET request:

   url

   copy

   https://graph.microsoft.com/v1.0/applications/{application-id}/extensionProperties

   • For example, GET https://graph.microsoft.com/v1.0/applications/8ec36bea-9fca-4aab-bacc-fb28d1bbb25d/extensionProperties

   • Take note of the value.name in the response. It should have a format like extension_{extension-id}_graphos_graph_roles

   

4. Retrieve user ID of the user whose graph-specific roles you want to set. You can view a user's ID from Users > (Select User) > Overview > Object ID.

   

5. Define as many graph-specific roles as you like on the user with the following PATCH request:

   url

   copy

   https://graph.microsoft.com/v1.0/users/{user-id}

   • With a request body with the following format:

     JSON

     copy

     {
       "{extension-name}":
           [
               "{graph-id}:{graph-specific-role}",
               "{graph-id}:{graph-specific-role}"
           ]
     }

     • The extension name is what you saved after making the GET request in step 2.

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

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

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

     • For example, PATCH https://graph.microsoft.com/v1.0/user/s456fc1be-7809-461a-8e0f-2884f5791af0 with the following request body:

       JSON

       copy

       {
         "extension_d7ebe566a2e2402c88e09e105336a3bf_graphos_graph_roles":
             [
                 "graph-1:GRAPH_ADMIN",
                 "graph-2:DOCUMENTER"
             ]
       }

     You should receive a successful response, but the response preview won't show any information.

     

     You confirm that roles were set in the next step.

6. Confirm the extension is set on the user with the following GET request:

   url

   copy

   https://graph.microsoft.com/v1.0/users/{user-id}?$select=<extension-name>

   • For example, GET https://graph.microsoft.com/v1.0/user/s456fc1be-7809-461a-8e0f-2884f5791af0?$select=extension_d7ebe566a2e2402c88e09e105336a3bf_graphos_graph_roles

   • You should see the array of graph IDs and roles in the response.

     

7. Add the graphos_graph_roles claim to the Entra application:

   • In your Microsoft Entra admin center, go to Identity > Applications > Enterprise applications and select the GraphOS application you previously created. Open the Single sign-on section and click Edit next to Attributes & Claims.

   • Click +Add new claim and give your new claim the name graphos_graph_roles. Leave the Namespace blank.

   • Expand the Claim conditions section and select the following:

     • User type: Members

     • Scoped Groups: Select all Entra ID groups that should have this claim.

     • Source: Directory schema extension

     • Value: In the modal that appears, select the Entra application, then in the Add Extension Attributes modal, select the user.graphos_graph_rolescustom extension you previously created.

     • Click Add.

     

     • Save the new claim.

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.