> For the complete documentation index, see [llms.txt](https://docs.stacksync.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.stacksync.com/two-way-sync/features/security/sso-and-scim/okta-stacksync.md).
# 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
.png?alt=media&token=220fbd5c-cf1f-465a-8b49-e57f4ce834e2)
