Configuring SCIM in Okta for LinearB

Overview

This article provides step-by-step instructions to configure SCIM (System for Cross-domain Identity Management) in Okta for LinearB. It also ensures that the correct naming convention is applied to avoid inconsistencies in user provisioning.

Requirements

LinearB supports SCIM V2.0 and adheres to the User Core Schema for user creation and updates.

• SCIM version: V2.0
• Supported schema: urn:ietf:params:scim:schemas:core:2.0:User

Prerequisites

SCIM-based user provisioning is available to Enterprise customers. Ensure you have:

• An admin account in Okta.
• Access to LinearB Company Settings.
• SCIM API token from LinearB.

Key Features

• Auto-provisioning: Users assigned to the LinearB application in Okta are automatically created in LinearB.
• User Attribute Updates: Changes in Okta sync automatically to LinearB.
• User Deactivation: Deactivated users in Okta are automatically removed from LinearB.

Step 1: Enable SCIM in LinearB

1. In LinearB, go to Company Settings > Settings, and click the API Tokens tab.
2. Click Create API Token, enter a label, and click Create.

1. Copy your new token immediately, as you won’t be able to view it again later.
2. Navigate to Authentication > SCIM Provisioning.
3. Enable SCIM and click Save.

Step 2: Configure SCIM in Okta

2.1 Enable SCIM Provisioning

1. In Okta, go to General Settings for the LinearB app.
2. Click Enable SCIM Provisioning and save changes.

2.2 Set Up SCIM Connection

1. Go to the Provisioning tab in the LinearB Okta app.
2. Click Edit and enter the following details:
   • 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: Enter the LinearB API Token from Step 1
3. Click Save, and run Test Connector Configuration to validate.

2.3 Enable Provisioning Actions

To ensure proper provisioning, enable the following actions in Okta:

1. In Provisioning to App, enable:
   • Create Users
   • Update User Attributes
   • Deactivate Users
2. Click Save to confirm the settings.

Step 3: Configure User Attributes in Okta

3.1 Map User Attributes

1. Go to Directory > Profile Editor > Select LinearB App > Click Add Attribute.
2. Configure the following attributes:
   • User Role
     • Data Type: String
     • Display Name: User role
     • Variable Name: userRole
     • External Name: userRole
     • External Namespace: urn:ietf:params:scim:schemas:core:2.0:User
     • Description: LinearB user role
     • Enum Values:
       • ADMIN → admin
       • EDITOR → editor
       • VIEWER → viewer
     • Attribute required: Yes
     • Attribute Type:
       • Select Personal if SCIM provisioning executes when attaching a single user to the Okta LinearB app.
       • Select Group if SCIM provisioning executes when attaching a group to the Okta LinearB app.
3. Click Save and Add Another.

1. Configure the following attributes:
   • Scope Team IDs
     • Data Type: Number array
     • Display Name: Team scope
     • Variable Name: scopeTeamIds
     • External Name: scopeTeamIds
     • External Namespace: urn:ietf:params:scim:schemas:core:2.0:User
     • Description: Teams accessible to the user
     • Attribute required: No
     • Attribute Type:
       • Select Personal if SCIM provisioning executes when attaching a single user to the Okta LinearB app.
       • Select Group if SCIM provisioning executes when attaching a group to the Okta LinearB app.
2. Click Save.

3.2 Configure Okta User Custom Fields

To ensure SCIM provisioning functions correctly, custom attributes must be configured for Okta users.

1. Go to Directory > Profile Editor > Select Okta User.

1. Click Add Attribute and configure the following fields:
   • User Role (See Step 3.1 for details on values and mappings)

     

   • Scope Team IDs (See Step 3.1 for details on values and mappings)

   

3.3 Map Attributes to User Profile

Mapping User Role

This configuration ensures that the correct user role is mapped in Okta and synchronized with LinearB.

Mapping Team Scope

Ensure that the default value {} is properly set to avoid mapping errors.

We now need to ensure that the attributes leveraged by the SCIM integration will be sent.

1. In Okta, navigate to Applications > LinearB > General > Edit SAML settings.
2. Create the following mapping under Attribute Statements to ensure proper user provisioning in LinearB:
   • Name: userName
     • Value: ${user.login}
   • Name: userRole
     • Value: ${user.userType}
   • Name: scopeTeamIds
     • Value: ${user.teamIds}
     • Name: userName
       • Value: ${user.login}
     • Name: userRole
       • Value: ${user.userType}
     • Name: scopeTeamIds
       • Value: ${user.teamIds}
3. Click Save to apply the mappings.
4. In Okta, navigate to Applications > LinearB > General > Edit SAML settings.
5. Create the following mapping under Attribute Statements:
   • Name: userName
   • Name: userRole
   • Name: scopeTeamIds
   • • Value: ${user.teamIds}
     • Value: ${user.userType}
     • Value: ${user.login}
6. Go to Applications > LinearB App > Provisioning > To App.
7. Scroll down and click the Pencil Icon to map attributes.
8. Map User Role and Team Scope, setting {} as the default value.
9. Click Save.

Step 4: Assign Users

1. In Okta, go to LinearB Application > Assignments.
2. Click Assign > Assign to People.

Select a user, set User Role and Team Scope.

• Example: Team ID: 74981, Group Name: SCIM Tutorial, and ID: 68250, Team Name: Beatles
• To retrieve the internal IDs of LinearB teams, please use public API or LinearB platform.

1. Click Save and Go Back > Done.

Step 5: Validate SCIM Setup

Proper validation ensures SCIM is working correctly.

In Okta

• Navigate to LinearB Application > Assignments.
• Confirm the assigned user has the correct User Role and Team Scope.
• Verify that SCIM provisioning actions (Push New Users, Profile Updates, etc.) are functioning as expected.

In LinearB

• Check that the user appears in Company Settings > Users.
• Verify that the User Role and Team Assignments are correct.
• Perform a manual resync if necessary by reassigning the user in Okta.

Naming Convention and Issue Resolution

Issue: Incorrect Naming Format in LinearB

Problem: Some users appear with an incorrect username (e.g., I67584@company.com instead of johndoe@company.com).

Solution: Enforce Proper User Mapping

To configure userName mapping:

1. Go to LinearB application in Okta.
2. Click General > SAML Settings > Edit.
3. Click Next.
4. Under Attribute Statements, create a field name userName, and and set the corresponding value for the userName.
   Example:
   • Field Name: userName
   • Value: ${user.login}
5. Click Next and Finish.

Expected Outcome

• Users will now appear with their correct email-based username instead of numeric IDs.
• Consistent naming conventions across all accounts.

Edge Cases and Troubleshooting

Edge Case 1: User Already Exists with a Different Username

Issue: If a user was manually created in LinearB before SCIM provisioning, their username may differ.

Solution:

• Manually update the username in LinearB to match the expected SCIM format.
• Alternatively, remove and reassign the user through Okta.

Edge Case 2: Missing Attributes in SCIM Response

Issue: User attributes do not appear correctly in LinearB.

Solution:

• Ensure that all custom attributes (userRole, scopeTeamIds) are mapped correctly in Okta.
• Verify that the SCIM provisioning actions are enabled in Okta.
• Run the Test Connector to check for missing fields.

Edge Case 3: User Not Being Assigned to the Correct Team

Issue: A provisioned user does not receive the expected team assignments.

Solution:

• Verify that the Team Scope attribute (scopeTeamIds) is configured correctly.
• Ensure that the user has been assigned to a team in Okta Assignments.
• Check LinearB’s API or UI for manually assigned teams and adjust accordingly.

Edge Case 4: SCIM Connector Fails During Setup

Issue: SCIM provisioning fails when testing the connector.

Solution:

• Confirm that the SCIM Base URL and API Token are correctly entered.
• Ensure the authentication mode is set to HTTP Header.
• Check Okta logs for specific error messages and troubleshoot accordingly.

Summary

By following this guide, SCIM in Okta is correctly configured for LinearB, ensuring proper user provisioning, role assignments, and naming conventions.

For additional support, contact LinearB Support.