OKTA Stacksync

This guide will walk you through setting up automatic user provisioning between Okta and Stacksync.

OverviewCopy Anchor Link

By the end of this guide, you will have:

• ✅ SAML-based Single Sign-On configured
• ✅ Automatic user provisioning via SCIM
• ✅ Role-based access control
• ✅ Users automatically created/updated/deactivated in Stacksync

Estimated time: 30–45 minutes

PrerequisitesCopy Anchor Link

Before you begin, ensure you have:

• Okta admin access
• Stacksync owner account
• Your company's email domain (e.g., acme.com)
• List of users who should have access

Supported FeaturesCopy Anchor Link

The following SAML 2.0 features are supported:

SCIM Provisioning FeaturesCopy Anchor Link

The following SCIM 2.0 provisioning features are supported:

SCIM AttributesCopy Anchor Link

The following user attributes are supported for SCIM provisioning operations:

Note: The email attribute is immutable. Once a user is created, their email address cannot be updated through SCIM. To change a user's email, you must deactivate the existing user and create a new one with the updated email.

Additional FeaturesCopy Anchor Link

NotesCopy Anchor Link

• SP-initiated SSO: Users can initiate login from the Stacksync login page by entering their email address. They will be redirected to Okta for authentication.
• IdP-initiated SSO: Users can initiate login directly from their Okta dashboard by clicking the Stacksync app tile.
• SCIM Provisioning: Automatic user lifecycle management including creation, updates, and deactivation. Each workspace requires a separate SCIM app configuration.
• Role-Based Access Control: Users can be assigned viewer or editor roles through Okta group membership.

Important NotesCopy Anchor Link

• You will create one "Stacksync - SSO" app for your entire organization
• You will create one "Stacksync - SCIM" app per workspace
• If you have multiple workspaces (e.g., dev, staging, production), you must set up a separate SCIM app for each
• Each workspace has independent RBAC enforcement

Part 1: Configure SAML Single Sign-OnCopy Anchor Link

The SSO configuration connects your Okta organization to Stacksync. You only need to complete this once for your entire organization.

Step 1.1: Add the Stacksync SSO AppCopy Anchor Link

1. Sign in to your Okta Admin Console
2. Navigate to Applications → Applications
3. Click Browse App Catalog
4. Search for and select Stacksync - SSO
5. Click Add Integration

Step 1.2: Configure Application SettingsCopy Anchor Link

1. In the application setup form, enter:
   • Organization Domain: Your company domain with dashes instead of dots (e.g., acme-com for acme.com)
2. Click Done

Step 1.3: Retrieve SAML Configuration URLsCopy Anchor Link

1. Navigate to the General tab
2. Scroll down to App Embed Link
3. Copy and save the embed link
4. Navigate to the Sign On tab
5. Copy and save the Metadata URL

Step 1.4: Configure SSO in StacksyncCopy Anchor Link

Note: The SSO configuration should only be done once per company domain. All workspaces will share the same SSO configuration.

1. Navigate to your Stacksync workspace settings
2. Select Okta as your identity provider
3. Upload the SAML metadata or enter the metadata URL from Step 1.3
4. (Optional) Enable Restrict login to SSO only for this domain to require SSO authentication for all users with your domain
5. Click Continue

You should now see a confirmation page with all the necessary information to complete the setup.

Part 2: Set Up Automatic User Provisioning (SCIM)Copy Anchor Link

The SCIM configuration enables automatic user provisioning. You must complete this for each Stacksync workspace.

Step 2.1: Add the Stacksync SCIM AppCopy Anchor Link

1. In your Okta Admin Console, navigate to Applications → Applications
2. Click Browse App Catalog
3. Search for and select Stacksync - SCIM
4. Click Add Integration
5. Enter your Workspace ID when prompted
6. Click Done

Step 2.2: Generate a Workspace API KeyCopy Anchor Link

1. Navigate to your Stacksync workspace settings
2. Scroll down to Stacksync Workspace API Key
3. Click Create API Key
4. Save the generated API key securely

Step 2.3: Enable API IntegrationCopy Anchor Link

1. Return to your Okta Admin Console
2. Open the Stacksync SCIM application you created
3. Navigate to the Provisioning tab
4. Click Configure API Integration
5. Check Enable API Integration
6. Paste your API key from Step 2.2
7. Click Test API Credentials
8. Verify that you see a success message
9. Click Save

Step 2.4: Configure Provisioning SettingsCopy Anchor Link

1. After saving, the page will display additional options
2. Click Edit in the To App section
3. Enable the following options:
   • Create Users
   • Update User Attributes
   • Deactivate Users
4. Disable Set password when creating new users
5. Click Save

Part 3: Configure Role Attribute MappingsCopy Anchor Link

App roles define which permission level users have in Stacksync (viewer or editor).

Step 3.1: Access the Profile EditorCopy Anchor Link

1. In the Provisioning tab, scroll down to Attribute Mappings
2. Click Go to Profile Editor

Step 3.2: Add the Roles AttributeCopy Anchor Link

1. Click + Add Attribute
2. Fill in the following fields:
   • Data type: string array
   • Display name: roles
   • Variable name: roles
   • External name: roles
   • External namespace: urn:ietf:params:scim:schemas:core:2.0:User
   • Description: SCIM role attribute for Stacksync app
   • Enum: Enabled
   • Attribute members: viewer, editor
   • Attribute required: Yes
   • Attribute type: Group
   • Group Priority: Use Group Priority
3. Click Save

Step 3.3: Configure Role Mapping ExpressionCopy Anchor Link

1. Return to your SCIM application

2. Under Attributes, click Mappings

3. Switch to the Okta User to Stacksync tab

4. Find the roles attribute in the mapping list

5. Add the following expression:

   Copy Text

   isMemberOfGroupName("Stacksync editors") ? {"editor"} : {"viewer"}

6. Click Save

Part 4: Create Groups and Assign UsersCopy Anchor Link

Step 4.1: Create Stacksync GroupsCopy Anchor Link

1. Navigate to Directory → Groups
2. Click Add Group
3. Create two groups:
   • Stacksync Editors — Users with editor permissions
   • Stacksync Viewers — Users with read-only permissions

Step 4.2: Add Users to GroupsCopy Anchor Link

1. Open each group you created
2. Click Assign People
3. Select the users who should have that access level
4. Click Save

Step 4.3: Assign Groups to the ApplicationCopy Anchor Link

1. Return to your Stacksync SCIM application
2. Navigate to the Assignments tab
3. Click Assign → Assign to Groups
4. Select Stacksync Editors
5. In the assignment dialog, set the roles field to editor by clicking the override text and choosing the radio button editor
6. Click Save and Go Back
7. Repeat for Stacksync Viewers, setting the roles field to viewer
8. Click Done

That's it! 🎉

TroubleshootingCopy Anchor Link

Common IssuesCopy Anchor Link

User not provisioned to StacksyncCopy Anchor Link

• Verify the API key is correct in the Provisioning settings
• Check that the user is assigned to the Stacksync SCIM application
• Ensure the user has a valid role assigned (viewer or editor)

Role not updatingCopy Anchor Link

• Verify the role mapping expression is correct
• Check that the user is in the correct Okta group (Stacksync Editors or Stacksync Viewers)
• Try removing and re-adding the user to the group

SSO login failsCopy Anchor Link

• Verify the Metadata URL is correct in Stacksync settings
• Check that the user's email domain matches the configured SSO domain
• Ensure the user is assigned to the Stacksync SSO application

API credentials test failsCopy Anchor Link

• Verify the Workspace ID is correct
• Regenerate the API key in Stacksync workspace settings
• Ensure you're using the correct workspace

SupportCopy Anchor Link

For additional assistance, contact Stacksync support at support@stacksync.com