# OKTA Stacksync

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**

<figure><img src="https://3470290772-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F04Dw47ioVxOWo43qmOru%2Fuploads%2FCAfn4CYIyDv0wwNQ0Awh%2FScreen%20Shot%202025-12-19%20at%208.08.58%20PM.png?alt=media&#x26;token=dda73b43-0e82-4c92-b391-30a1a92d66a0" alt=""><figcaption></figcaption></figure>

### 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**

<figure><img src="https://3470290772-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F04Dw47ioVxOWo43qmOru%2Fuploads%2F9fHFY7kjYWVKhYHkhkg8%2FScreen%20Shot%202025-11-12%20at%2012.14.18%20AM.png?alt=media&#x26;token=3dcc8645-ac0f-4cc7-beac-4e452690a164" alt=""><figcaption></figcaption></figure>

<figure><img src="https://3470290772-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F04Dw47ioVxOWo43qmOru%2Fuploads%2FtTk5sGMxvo5XJpehhloA%2FScreen%20Shot%202025-11-12%20at%2012.13.55%20AM.png?alt=media&#x26;token=c281a338-fb0e-41ae-9c17-b022bbbf3b20" alt=""><figcaption></figcaption></figure>

#### 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.

<figure><img src="https://3470290772-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F04Dw47ioVxOWo43qmOru%2Fuploads%2FYQXiKT3dpXjwIbkjvvJf%2FScreen%20Shot%202025-12-19%20at%206.23.27%20PM.png?alt=media&#x26;token=3746883f-6112-41a8-99c3-b1bb1eda7579" alt=""><figcaption></figcaption></figure>

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**

<figure><img src="https://3470290772-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F04Dw47ioVxOWo43qmOru%2Fuploads%2FRbJhwtvKV20Q5xLzkslz%2FScreen%20Shot%202025-12-19%20at%208.10.48%20PM.png?alt=media&#x26;token=d688600c-75a9-476b-863d-0fb8e4426bff" alt=""><figcaption></figcaption></figure>

#### 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

<figure><img src="https://3470290772-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F04Dw47ioVxOWo43qmOru%2Fuploads%2FjXN2dfS6jeNOkV44JrI6%2FScreen%20Shot%202025-11-12%20at%2012.33.58%20AM.png?alt=media&#x26;token=2a6773fa-35d3-4b26-85fd-8c5e3bdddc3b" alt=""><figcaption></figcaption></figure>

<figure><img src="https://3470290772-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F04Dw47ioVxOWo43qmOru%2Fuploads%2F1tgdhHJZ7HCd7yXCoJDL%2FScreen%20Shot%202025-11-12%20at%2012.33.23%20AM.png?alt=media&#x26;token=9113d87c-a317-41c3-bc02-4b96f63acc64" alt=""><figcaption></figcaption></figure>

#### 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**

<figure><img src="https://3470290772-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F04Dw47ioVxOWo43qmOru%2Fuploads%2Fen16YypARFFgS9SgPqan%2FScreen%20Shot%202025-11-12%20at%2012.31.31%20AM.png?alt=media&#x26;token=0745960d-c034-49c0-8644-f5ba40d79d4c" alt=""><figcaption></figcaption></figure>

#### 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**

<figure><img src="https://3470290772-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F04Dw47ioVxOWo43qmOru%2Fuploads%2Fnzu5or4ac58L1vAXIUau%2FScreen%20Shot%202025-11-12%20at%2012.42.45%20AM.png?alt=media&#x26;token=85146203-3c03-4552-9502-5d469f324c28" alt=""><figcaption></figcaption></figure>

<figure><img src="https://3470290772-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F04Dw47ioVxOWo43qmOru%2Fuploads%2F4zMceKQDuvbEYr1RzXkt%2FScreen%20Shot%202025-11-12%20at%2012.44.24%20AM.png?alt=media&#x26;token=d2b53294-982a-4bab-a77a-87a0cc1455de" alt=""><figcaption></figcaption></figure>

### 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**

<figure><img src="https://3470290772-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F04Dw47ioVxOWo43qmOru%2Fuploads%2FzVONxstaPAn15rgN080a%2FScreen%20Shot%202025-11-12%20at%2012.47.38%20AM.png?alt=media&#x26;token=19724db0-10b8-4c0e-91db-407e2246d7e3" alt=""><figcaption></figcaption></figure>

#### 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**

<figure><img src="https://3470290772-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F04Dw47ioVxOWo43qmOru%2Fuploads%2FR46nF8W7HNJi7vuL43Aq%2Fimage.png?alt=media&#x26;token=32494410-605b-4486-9d52-8f64289b134c" alt=""><figcaption></figcaption></figure>

<figure><img src="https://3470290772-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F04Dw47ioVxOWo43qmOru%2Fuploads%2FFh5vPR181jVx5vmXlKh3%2Fimage%20(11).png?alt=media&#x26;token=9463442f-b911-4510-b735-7fd736fd54d6" alt=""><figcaption></figcaption></figure>

#### 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**

<figure><img src="https://3470290772-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F04Dw47ioVxOWo43qmOru%2Fuploads%2FtY3crrE05fPC1pN8i6SD%2Fimage.png?alt=media&#x26;token=4216ddf9-3cfa-40d3-9a52-c5a2cce83db9" alt=""><figcaption></figcaption></figure>

<figure><img src="https://3470290772-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F04Dw47ioVxOWo43qmOru%2Fuploads%2FQardJHxukOJ5fGFaN5ux%2FScreen%20Shot%202025-11-12%20at%201.00.54%20AM.png?alt=media&#x26;token=2555f35b-871e-44f2-a46b-a51117c7c601" alt=""><figcaption></figcaption></figure>

<figure><img src="https://3470290772-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F04Dw47ioVxOWo43qmOru%2Fuploads%2F5wvM5kjxWXKFzarMCXaX%2Fimage.png?alt=media&#x26;token=6760bdd6-03b6-4147-b50f-44f33854b205" alt=""><figcaption></figcaption></figure>

### 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

<figure><img src="https://3470290772-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F04Dw47ioVxOWo43qmOru%2Fuploads%2FMbKp88UtHkM0h2MKwh7a%2Fimage.avif?alt=media&#x26;token=2f374b2f-ae81-483f-82af-76952acd4a23" alt=""><figcaption></figcaption></figure>

#### 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**

<figure><img src="https://3470290772-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F04Dw47ioVxOWo43qmOru%2Fuploads%2FcRJpwKjr6CFZHs7YPAyg%2Fimage%20(12).png?alt=media&#x26;token=efb00d7d-c28c-4fc8-9652-a0e3a08c8fa6" alt=""><figcaption></figcaption></figure>

#### 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**

<figure><img src="https://3470290772-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F04Dw47ioVxOWo43qmOru%2Fuploads%2FFOuJL7Gzv2u7J9yN1ra3%2Fimage.png?alt=media&#x26;token=70853092-6eb1-4ece-b780-97e92f7c880b" alt=""><figcaption></figcaption></figure>

<figure><img src="https://3470290772-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F04Dw47ioVxOWo43qmOru%2Fuploads%2Fqe1zRUiHcJ6W6331OZKd%2FScreen%20Shot%202025-11-12%20at%202.47.11%20AM.png?alt=media&#x26;token=4feb2efc-29ff-4c05-96d2-e979fc51ac5f" alt=""><figcaption></figcaption></figure>

<figure><img src="https://3470290772-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F04Dw47ioVxOWo43qmOru%2Fuploads%2Fa9LKJo9y3H4HFmK7Fybu%2FScreen%20Shot%202025-11-12%20at%202.47.30%20AM.png?alt=media&#x26;token=1cf57405-2ec5-4bae-8adf-6a6429b3678b" alt=""><figcaption></figcaption></figure>

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 <support@stacksync.com>
