Setup Guide - Okta SCIM

Configuring SCIM Provisioning in Okta for LinearB

Use this guide to configure SCIM-based user provisioning between Okta and LinearB. SCIM lets Okta automatically create, update, and deactivate users in LinearB based on your identity provider, including role and team-scope information.

---

Overview

• SCIM version: V2.0
• Supported schema: urn:ietf:params:scim:schemas:core:2.0:User
• Provisioning direction: Okta → LinearB

What SCIM does

• Automatically provisions new users into LinearB when they’re assigned to the LinearB app in Okta.
• Updates user attributes (including role and team scope) when they change in Okta.
• Deactivates LinearB users when they are deactivated in Okta.
• Reduces manual administration and keeps identity and access in sync.

Before you begin

• Plan: SCIM provisioning is available to Enterprise customers.
• Permissions: Okta admin and LinearB admin access.
• LinearB access: Ability to open Company Settings in LinearB.
• SCIM API token: Generated from LinearB (created in this guide).

---

Step 1 – Enable SCIM in LinearB

1.1 Create an API token

1. In LinearB, go to Company Settings → API Tokens.
2. Click Create API Token, enter a descriptive label (for example, Okta SCIM), and click Create.
3. Copy the new token immediately and store it securely. You will not be able to view it again later.

1.2 Enable SCIM provisioning

1. In Company Settings → SCIM.
2. If you do not see the SCIM tab, reach out to your LinearB contanct or LinearB Support to enable SCIM for your account.
3. Enable SCIM and click Save.

You now have:

• An active SCIM API token.
• SCIM provisioning enabled in LinearB.

---

Step 2 – Configure SCIM in Okta

2.1 Enable SCIM provisioning in Okta for the LinearB app

1. In the Okta Admin Console, open your LinearB application.
2. From the app, go to General Settings (or the Provisioning tab, depending on your Okta UI).
3. Enable SCIM provisioning / API integration for the app.

2.2 Set up the SCIM connection

1. Open the Provisioning tab in the LinearB Okta app.
2. Click Edit in the SCIM connection section and configure:

• SCIM Connector Base URL: https://public-api.linearb.io/scim/api/v2
• Unique Identifier Field for Users: email
• Supported Provisioning Actions:
  • Push New Users
  • Push Profile Updates
  • Push Groups
• Authentication Mode: HTTP Header
• HTTP Header / API Token: paste the LinearB API token you created in Step 1.

3. Save your changes.
4. Run Test Connector Configuration to validate the connection.

If the connector test fails, double-check the SCIM base URL and that the API token is correct and active.

2.3 Enable provisioning actions

1. Still in the LinearB Okta app, under Provisioning to App, enable:

• Create Users
• Update User Attributes
• Deactivate Users

2. Click Save to confirm the settings.

When these actions are enabled, Okta will create, update, and deactivate LinearB users automatically based on assignments to the LinearB application.

---

Step 3 – Configure user attributes & role provisioning

LinearB supports standard SCIM core attributes and two important custom attributes used for roles and team scope:

• userRole – the LinearB role (admin, editor, viewer).
• scopeTeamIds – IDs of teams the user should have access to in LinearB.

3.1 Create custom attributes on the LinearB app profile

1. In Okta Admin, go to Directory → Profile Editor.
2. Select the LinearB application profile.
3. Click Add Attribute and create the following:

User Role attribute (userRole)

• Display name: User role
• Variable name: userRole
• External name: userRole
• External namespace: urn:ietf:params:scim:schemas:core:2.0:User
• Data type: String
• Description: LinearB user role
• Enum values (recommended):
  • ADMIN → admin
  • EDITOR → editor
  • VIEWER → viewer
• Attribute required: Yes
• Attribute type: Personal or Group (depending on whether you provision per user or by group).

Team Scope attribute (scopeTeamIds)

• Display name: Team scope
• Variable name: scopeTeamIds
• External name: scopeTeamIds
• External namespace: urn:ietf:params:scim:schemas:core:2.0:User
• Data type: Number array
• Description: Teams accessible to the user
• Attribute required: No
• Attribute type: Personal or Group (matching your provisioning model).

Save each attribute after configuration.

3.2 Add corresponding fields to the Okta User profile

To push role and scope values from the Okta user to LinearB, you also need matching fields on the Okta User profile.

1. In Directory → Profile Editor, select Okta User.
2. Add custom attributes corresponding to userRole and scopeTeamIds.
3. Map the Okta User fields to the LinearB app attributes created in step 3.1.

Once mapped, Okta will send the user’s LinearB role and team scope to SCIM when the user is assigned.

---

Step 4 – Assign users and groups

4.1 Assign users / groups to the LinearB app

1. In Okta, open the LinearB application.
2. Go to the Assignments tab.
3. Click Assign → Assign to People or Assign to Groups.
4. Select the users or groups you want to provision and click Assign.

4.2 Set user role and team scope

1. For each assigned user (or group):

• Set User Role to one of:
  • admin
  • editor
  • viewer
• Optionally, set Team Scope (scopeTeamIds) to a comma-separated list of LinearB team IDs the user should access.

To find LinearB team IDs, use LinearB public Teams API, then enter the numeric IDs into scopeTeamIds.

4.3 Validate provisioning in LinearB

1. In LinearB, go to Company Settings → Users & Teams.
2. Confirm that newly assigned Okta users appear in the list.
3. Verify that each user has the expected role and team assignments.

---

Troubleshooting

Provisioning fails or connector test fails

• Verify that the SCIM Connector Base URL is exactly https://public-api.linearb.io/scim/api/v2.
• Confirm the API token is valid and has been pasted correctly in the HTTP header.
• Ensure HTTP Header is selected as the authentication mode.
• Check Okta system logs for detailed error messages.

Users are not being created

• Confirm users or groups are assigned to the LinearB app in Okta.
• Make sure Create Users is enabled under Provisioning to App.

User attributes or roles not updating

• Ensure Update User Attributes is enabled under provisioning settings.
• Verify that the custom attributes userRole and scopeTeamIds are correctly mapped from Okta User → LinearB app profile.
• Run a manual resync by unassigning and reassigning the user in Okta if needed.

User not assigned to expected teams

• Confirm that the scopeTeamIds attribute contains the correct LinearB team IDs.
• Verify that the IDs match existing teams in LinearB.
• Check for conflicting manual team assignments in LinearB.

User already exists with a different username

• If a user was manually created in LinearB before SCIM, their username may not match the Okta value.
• Align the username in LinearB with the expected SCIM username, or remove and reassign the user from Okta.

---

FAQs

Which IdP is supported for SCIM?
SCIM provisioning is currently supported with Okta. Other identity providers are not yet supported for SCIM.

How are roles assigned?
Roles are controlled via the userRole SCIM attribute. Okta sends one of admin, editor, or viewer, which LinearB uses to set the user’s role.

Does SCIM delete users from LinearB?
No. When a user is deactivated in Okta and SCIM deactivation is enabled, LinearB deactivates the user rather than deleting them.

Can SCIM automatically assign users to teams?
Yes. Use the scopeTeamIds attribute to send LinearB team IDs from Okta so users receive the appropriate team access.

---

Need help?
If you encounter issues or have edge cases not covered here, please contact LinearB Support.