# OKTA 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 --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.stacksync.com/security-and-other-resources/identity-and-access-management/sso/okta.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.