OKTA Stacksync

SCIM setup instructions

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

Overview

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

Prerequisites

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 Features

The following SAML 2.0 features are supported:

Feature	Supported
SP-initiated SSO	Yes
IdP-initiated SSO	Yes
Just-In-Time (JIT) Provisioning	Yes
Single Logout (SLO)	No

SCIM Provisioning Features

The following SCIM 2.0 provisioning features are supported:

Feature	Supported
Push New Users	Yes
Push Profile Updates	Yes
Push User Deactivation	Yes
Reactivate Users	Yes
Push Groups	No
Import Users	No
Import Groups	No
Sync Password	No

SCIM Attributes

The following user attributes are supported for SCIM provisioning operations:

Attribute	Required	Immutable	Description
userName	Yes	No	User's unique identifier (typically email)
email	Yes	Yes	User's email address (cannot be changed via SCIM)
givenName	No	No	User's first name
familyName	No	No	User's last name
roles	Yes	No	User's role: viewer or editor

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 Features

Feature	Supported
Force Authentication	No
Encrypted Assertions	No
Signed Requests	Yes

Notes

• 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 Notes

• 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-On

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 App

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 Settings

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 URLs

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 Stacksync

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.

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

Part 2: Set Up Automatic User Provisioning (SCIM)

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

Step 2.1: Add the Stacksync SCIM App

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 Key

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 Integration

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 Settings

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 Mappings

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

Step 3.1: Access the Profile Editor

1. In the Provisioning tab, scroll down to Attribute Mappings

2. Click Go to Profile Editor

Step 3.2: Add the Roles Attribute

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 Expression

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:

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

6. Click Save

Part 4: Create Groups and Assign Users

Step 4.1: Create Stacksync Groups

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 Groups

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 Application

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! 🎉

Troubleshooting

Common Issues

User not provisioned to Stacksync

• 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 updating

• 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 fails

• 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 fails

• Verify the Workspace ID is correct

• Regenerate the API key in Stacksync workspace settings

• Ensure you're using the correct workspace

Support

For additional assistance, contact Stacksync support at [email protected]