Set up SCIM with Okta

Okta supports two methods for connecting to Attio: a developer token or OAuth 2.0. The developer token method is simpler and suitable for most organizations. OAuth 2.0 is available for organizations with stricter security requirements.

PrerequisitesCopy link

Before you begin, ensure the following:

• You are on the Attio Enterprise plan.

• You are an Attio workspace admin.

• Your Attio workspace has at least one verified domain.

• Choose whether to set automatic seat assignment.

Supported featuresCopy link

The following SCIM provisioning actions are supported by Attio:

• Create users

• Update user attributes

• Deactivate users

• Import users

• Import groups

• Push groups

Create a custom app integration in OktaCopy link

For general help with this process, see Create SWA app integrations in Okta's documentation.

1. In your Okta Admin Console, go to Applications > Applications.

2. Click Create App Integration.

3. Select SWA – Secure Web Authentication as the sign-in method and click Next.

4. Enter a name for the app, for example, "Attio SCIM".

5. Set App's login page URL to https://attio.com.

6. Click Next, leave the sign-in defaults as they are, and click Finish.

Enable SCIM provisioningCopy link

1. Open your new app and click the General tab.

2. Click Edit in the App Settings section.

3. Under Provisioning, select SCIM.

4. Click Save. A Provisioning tab appears at the top of the app.

From here, choose your connection method. Continue below to connect using a developer token, or skip to Connect using OAuth 2.0.

Connect using OAuth 2.0Copy link

OAuth 2.0 is available for organizations that require a more secure authentication method. This flow requires a developer account and a custom app on build.attio.com. For help getting started, see Attio's developer documentation.

Create an app on build.attio.comCopy link

1. Go to build.attio.com and sign in. You'll need a developer account.

2. Create a new app.

3. With the app selected, go to Scopes and set User Management to Read-write.

4. Go to the OAuth tab and find the Client ID and Client secret. You'll need these in Okta shortly.

Configure OAuth 2.0 in OktaCopy link

1. In your Okta app, click the Provisioning tab, then click Integration in the left sidebar.

2. Click Edit.

3. Under OAuth 2, set Grant Type to Authorization Code.

4. Fill in the following fields:

   • Access token endpoint URI: https://app.attio.com/oauth/token

   • Authorization endpoint URI: https://app.attio.com/authorize

   • Client ID: paste the Client ID from your Attio developer app

   • Client secret: paste the Client secret from your Attio developer app

5. Click Save.

Add the redirect URI to your Attio developer appCopy link

1. In your Okta app, click the General tab and scroll down to the App Embed Link section.

2. Copy the app ID from the embed link URL. It appears after home/ and before the next /, for example, integrator-1111111_basepointscim_1.

3. Construct your redirect URI in this format: https://system-admin.okta.com/admin/app/cpc/{app-id}/oauth/callback, replacing {app-id} with the value you copied.

4. Go back to your app on build.attio.com and add this URL as a redirect URI.

Authorize access to your workspaceCopy link

1. In your Okta app, click the Provisioning tab, then click Integration in the left sidebar.

2. At the bottom of the page, click Re-authenticate with SCIM.

3. You are taken to an Attio authorization page. Select the workspace you want to connect and click Confirm.

For more details on configuring OAuth 2.0 in Okta, see Add SCIM provisioning to app integrations in Okta's documentation.

Connect using a developer tokenCopy link

First, make sure you have at least one verified domain on your workspace.

To connect your IDP using a developer token, you’ll need to be an Attio admin.

1. Click your workspace name and select Workspace settings.

2. Click Developers in the sidebar.

3. Click + New access token.

4. Give the token a name, such as "SCIM Management".

5. Set User Management to Read-write.

6. Copy the token and paste it into your identity provider's SCIM configuration.

Connect to AttioCopy link

1. Click the Provisioning tab, then click Integration in the left sidebar.

2. Click Edit.

3. Fill in the following fields:

   • SCIM connector base URL: https://api.attio.com/scim/v2

   • Unique identifier field for users: userName

4. Under Supported provisioning actions, select the provisioning features you want to enable:

   • Import New Users and Profile Updates

   • Push New Users

   • Push Profile Updates

   • Push Groups

   • Import Groups

5. Set Authentication Mode to HTTP Header.

6. In Attio, copy the token you created earlier and paste it into the Bearer field for the HTTP Header Authorization.

7. Click Test Connector Configuration to confirm the setup is correct.

8. Once confirmed, click Save.

Configuration stepsCopy link

Okta is now connected to Attio. Any users you assign to this app in Okta will be provisioned as workspace members in Attio. Before provisioning users, you may want to configure automatic seat assignment. To learn more about how SCIM handles provisioning, roles, and teams, see Provision users and teams with SCIM.

Configure the roles attributeCopy link

Custom Okta app integrations don't include a roles attribute by default. You need to add it manually before provisioning users with specific roles.

Step 1: Add the attribute in the Profile Editor

1. In your Okta Admin Console, go to Directory > Profile Editor.

2. Under Users, click on the default Okta user.

3. Click + Add Attribute.

4. Configure the attribute with the following settings:

   • Data type: String

   • Display name: Attio Role

   • Enum: checked, with two values: Display name Admin, value admin and display name Member, value member

   • User permission: Read-Write

5. Click Save.

Step 2: Add the attribute to the Attio SCIM app profile

1. Navigate to the Attio SCIM application and go to the Provisioning tab.

2. Click To App and click Go to Profile Editor.

3. Click Add Attribute.

4. Configure the attribute with the following settings:

   • Data type: String

   • Display name: Attio Role

   • Enum: checked, with two values: Display name Admin, value admin and display name Member, value member

   • Attribute type: Group

   • Mutability: READ_WRITE

5. Click Save Attribute.

Step 3: Map the attribute to the app

1. In your Okta app, click the Provisioning tab.

2. Click To App under Settings.

3. Scroll down and click Show Unmapped Attributes.

4. Find the newly added attribute called Attio Role and click the edit button.

5. Set Attribute value to Map from Okta Profile and select the attribute created in step 1.

6. Set Apply on to Create and update.

7. Click Save.

Assign a userCopy link

1. In your Okta app, click the Assignments tab.

2. Click Assign, then select Assign to People.

3. Find the user you want to provision and click Assign.

4. Update the Attio Role attribute if needed, selecting Admin or Member.

5. Click Save and Go Back.

6. Repeat for any additional users, then click Done.

When a user is assigned, Attio checks whether a user with that email already exists in the workspace. If they do, the existing user is linked rather than a new one created. If they don't, a new workspace member is provisioned.

Assign a groupCopy link

1. In your Okta app, click the Assignments tab.

2. Click Assign, then select Assign to Group.

3. Find the group you want to provision and click Assign.

4. Update the Roles value if needed, selecting Admin or Member.

5. Click Save and Go Back.

6. Repeat for any additional groups, then click Done.

Deprovision a userCopy link

To suspend a user's Attio workspace membership from Okta:

1. In your Okta app, click the Assignments tab.

2. Click the X next to the user you want to remove.

3. Confirm you want to unassign the user.

The user is unassigned from the app and their Attio workspace membership is suspended.

Deprovision a groupCopy link

To suspend a user's Attio workspace membership from Okta:

1. In your Okta app, click the Assignments tab.

2. Navigate to Groups under Filters.

3. Click the X next to the group you want to remove.

4. Confirm you want to unassign the group.

The group is unassigned from the app and the Attio workspace memberships of users inside this group are suspended.

Update a user's roleCopy link

Once the roles attribute is configured, you can update a user's role directly from Okta.

1. Open your Attio SCIM app and click the Assignments tab.

2. Click the pencil icon next to the user.

3. Scroll down to the Attio Role attribute and select Admin or Member.

4. Click Save.

Push groupsCopy link

SCIM groups map to Attio teams. To create or link a team in Attio, use the Push Groups tab in your Okta app. Assigning a group from the Assignments tab only adds its members to the app; it does not create a team in Attio.

Push a group to create a new teamCopy link

1. In your Okta app, click the Push Groups tab.

2. Click Push Groups, then select Find groups by name.

3. Search for and select the group you want to push.

4. Click Save.

When a group is pushed, Attio creates a new team. Any members of that Okta group who are already in your Attio workspace are added to the team automatically.

Link a group to an existing teamCopy link

If you want to link an Okta group to a team that already exists in Attio, first make sure the team exists in Attio. If it doesn't, create it before continuing.

1. In your Okta app, click the Push Groups tab.

2. Click Refresh App Groups to make sure Okta has the latest list of Attio teams.

3. Click Push Groups, then select Find groups by name.

4. Search for and select the group.

5. Under Match result & push action, click Link Group. Okta will automatically find and select the matching Attio team.

6. Click Save.

To manage your groups in Okta, go to Directory > Groups in the Okta Admin Console.

When you unlink a group from the Push Groups tab, Okta will prompt you to choose whether to delete the corresponding team in Attio or keep it.