Set up SCIM with Okta
Configure Okta as your GraphOS organization's identity provider for user provisioning
This guide walks through configuring Okta as your GraphOS organization's identity provider (IdP) for SCIM-based user provisioning. Once you've set up your integration, Okta will automatically manage user and group provisioning and deprovisioning in GraphOS.
Prerequisites
Only GraphOS Org admins can set up SCIM.
You must have administrative access to your Okta account.
You must configure SSO before configuring SCIM.
Setup
Step 1: Obtain SCIM credentials
If you haven't already, request a SCIM URL from Apollo Support.
Go to your API keys in GraphOS Studio.
Generate a new API key and give it a descriptive name like
Okta SCIM key
.Save the API key securely. You'll need these in the next steps.
noteThe API key is only displayed once. If you lose it, you'll need to revoke the key and generate a new one.
Step 2: Configure SCIM in Okta
Log in to your Okta Administrator Dashboard.
Navigate to Applications > Applications and select the GraphOS application you created when setting up SSO.
In the General tab, locate the App Settings section and click Edit.
Next to Provisioning select SCIM, then click Save.
Open the Provisioning tab, then the Integration section from the left menu, and click Edit in the SCIM Connection section.
Enter the following values:
SCIM connector base URL: the SCIM URL provided by your Apollo contact
Unique identifier field for users:
userName
Supported provisioning actions:
Push New Users
Push Profile Updates
Push Groups
Set the Authentication Mode to HTTP Header.
Paste the API token you generated in GraphOS Studio into the Authorization field.
Click Test Connector Configuration to verify the connection. You should see a Connector configured successfully modal appear.
Click Save to complete setup.
Step 3: Confirm provisioning and attribute mappings
In the Provisioning tab of your GraphOS application in Okta:
Click Edit in the To App section.
Enable the following features:
Create Users
Update User Attributes
Deactivate Users
Click Save.
On the same page, in the Attribute Mapping section, ensure the following required attributes are mapped correctly:
userName
: Configured in Sign On settingsgivenName
:user.firstName
familyName
:user.lastName
email
:user.email
If you need to make any changes, click Go to Profile Editor.
This ensures that whenever one of these attributes is updated in your IdP those changes are automatically forwarded to GraphOS.
Step 4: Assign users to the GraphOS application
You've likely already completed this step when configuring SSO. You can follow these steps to double check your assignments and update them as necessary.
Navigate to the Assignments tab in your GraphOS application.
Click Assign and select either Assign to People or Assign to Groups.
Choose the users or groups you want to provision to GraphOS and click Assign.
Click Done.
Users assigned to the application will be automatically provisioned to GraphOS according to your provisioning configuration.
Assign GraphOS roles
Once you've set up SSO, each user assigned to your GraphOS integration receives the GraphOS organization's default role. To avoid manually setting a different role for each user, you can configure Okta to set GraphOS roles based on the Okta groups they belong to, before they log into GraphOS Studio for the first time. Updates to user permissions in Okta automatically propagate to GraphOS.
How role assignment works
GraphOS supports the following role assignment mechanisms:
- Setting organization-wide roles
- Setting graph-specific roles
If a user has both organization-wide and graph-specific 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 for SCIM-based role assignment
In your Okta Administrator Dashboard left navigation, go to Directory > Profile Editor.
Select the GraphOS Studio User for the application created during SSO configuration.
Click + Add Attribute and create this attribute
Data type:
string array
Display name:
GraphOS Roles
Variable name:
roles
Description:
GraphOS Studio roles
Enum: Check
Define enumerated list of values
and add the following values for organization-wide roles:Org Admin
:graphos_org_role:org_admin
Graph Admin
:graphos_org_role:graph_admin
Contributor
:graphos_org_role:contributor
Documenter
:graphos_org_role:documenter
Observer
:graphos_org_role:observer
Consumer
:graphos_org_role:consumer
Billing Manager
:graphos_org_role:billing_manager
Additionally, for any graph-specific roles you want to assign, add roles in this format:
Graph name and role
:graphos_graph_role:<graph-id>:<graph-role>
For example,
Docs sandbox admin
:graphos_graph_role:docs_sandbox:graph_admin
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
, andconsumer
.
Attribute type:
Group
Group priority:
Combine values across groups
Click Save Attribute.
Back in the Okta GraphOS Studio application, open the Assignments > Groups tab.
If the desired groups are already assigned to the application, click the pencil icon next to a group to edit it. Otherwise, assign the group by clicking Assign > Assign to Groups.
When editing or assigning a group, select the appropriate GraphOS Roles for each group at the bottom of the modal.
Click Save.
Once you've completed the above steps, role assignments will be automatically pushed to GraphOS whenever groups or users are provisioned or updated in Okta.