> 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/security-and-other-resources/identity-and-access-management/sso/okta-stacksync.md).

# OKTA Stacksync

SSO and SCIM for OKTA

{% hint style="info" %}
The Stacksync OKTA app is currently under review by OKTA. Until the app is published on OKTA marketplace, here is a guide to synchronize your OKTA users automatically into Stacksync by creating the SCIM app yourself

This setup takes \~10min
{% endhint %}

{% hint style="info" %}
SSO is part of the Stacksync Enterprise plan. Contact us at <sso@stacksync.com> to enable it on your workspace.
{% endhint %}

Notes:

* This setup needs to be implemented by an OKTA **ADMIN**
* The SSO part is done once for your whole company domain. The Stacksync side must be completed by a workspace member who logs in with an email on your company domain (e.g. `jane@acme.com`).
* The SCIM integration is associated to a unique Stacksync workspace. If you have multiple workspaces (such as dev, stage and prod) you will need to set up an SCIM app for each of these Stacksync workspaces. Each workspace has independent RBAC enforcement.

## SSO (SAML) setup instructions

1. In Stacksync, open **Workspace Settings** → **SCIM & SSO** and select `Okta` as the **Identity Provider**. Keep this page open: the **Preview** box shows the two values you need in Okta.

   <figure><img src="https://1234677496-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F4zoaoqcTuhTKzdRmiB6e%2Fuploads%2Fgit-blob-1bbd71ef227372f33f015be70e94ef7b71ab4022%2Fokta_stacksync_sso_preview.png?alt=media" alt="SCIM &#x26; SSO tab with Okta selected and the Preview box"><figcaption></figcaption></figure>
2. On your OKTA homepage go on the admin section

   <figure><img src="https://1234677496-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F4zoaoqcTuhTKzdRmiB6e%2Fuploads%2FB0CgwF9D0XTIqbfZXA5B%2Fimage.png?alt=media&amp;token=112a28b3-5c4b-47a3-928b-00cf6abe5bc8" alt=""><figcaption></figcaption></figure>
3. In the Applications section, create an App integration of type SAML 2.0

   <figure><img src="https://1234677496-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F4zoaoqcTuhTKzdRmiB6e%2Fuploads%2F4pXVoP7fxlP3bvqMPL3a%2Fimage.png?alt=media&amp;token=b9455e45-07e6-400f-99df-bffbb977aa30" alt=""><figcaption></figcaption></figure>

   <figure><img src="https://1234677496-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F4zoaoqcTuhTKzdRmiB6e%2Fuploads%2Fw7udU7p8Yhov9la7UPCr%2Fimage.png?alt=media&amp;token=581415b6-d3f8-4c4f-8cec-c4f83bf5ac89" alt=""><figcaption></figcaption></figure>
4. Give the App name to `Stacksync` and you can add the Stacksync app logo (download file below)

{% file src="/files/IP3EG3RYbdRz1yEcUcco" %}

5. Configure your SAML settings with:
   1. Single sign-on URL: the **Reply URL (ACS)** from the Stacksync Preview, e.g. `https://auth.stacksync.com/login/callback?connection=acme-com-sso-okta`
   2. Audience URI: the **Identifier (Entity ID)** from the Stacksync Preview, e.g. `urn:auth0:stacksync:acme-com-sso-okta`
   3. Application username: `Email`
   4. Update application username on `Create and update`
   5. Attribute Statements:
      1. name=`emails`
      2. name format=`Basic`
      3. value=`user.email`<br>

         <figure><img src="https://1234677496-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F4zoaoqcTuhTKzdRmiB6e%2Fuploads%2FXiLMyASYBc4nmroa07PS%2Fimage.png?alt=media&amp;token=59a9b464-1ef7-4511-a306-2008c75e2d23" alt=""><figcaption></figcaption></figure>
   6. You can skip the `Feedback` section and click `Finish`
6. In the Okta app, open the **Sign On** tab and copy the **Metadata URL** (it ends with `/sso/saml/metadata`).
7. Back in Stacksync (**Workspace Settings** → **SCIM & SSO**), paste the Metadata URL in **Okta SAML Metadata URL** and click **Continue**.

   * Keep **Restrict login to SSO only for this domain** checked if every user on your domain must log in through Okta. Uncheck it to let users keep their current login method as well.

   <figure><img src="https://1234677496-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F4zoaoqcTuhTKzdRmiB6e%2Fuploads%2Fgit-blob-66409e30130998142c59d57305cab344ca1689b3%2Fokta_stacksync_sso_metadata_url.png?alt=media" alt="Okta SAML Metadata URL field and Continue button"><figcaption></figcaption></figure>

   The page then shows your **Current SSO configuration**, and you're all set! :tada:

## SCIM setup instructions

1. On the General page of the SAML app you just created, enable SCIM provisioning.<br>

   <figure><img src="https://1234677496-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F4zoaoqcTuhTKzdRmiB6e%2Fuploads%2FLOH4YM0XxqQordTUaV5G%2Fimage.png?alt=media&amp;token=28085473-8c58-477f-958c-4d161007c199" alt=""><figcaption></figcaption></figure>
2. Go to the Stacksync **Workspace Settings** page at `https://app.stacksync.com` to find the information necessary for the next steps.
   1. Find your Stacksync `workspace_id` in the **General** tab.

      <figure><img src="https://1234677496-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F4zoaoqcTuhTKzdRmiB6e%2Fuploads%2Fgit-blob-6aec89bb64d4b58e8dd1aea10413eaeecd4387b4%2Fokta_stacksync_workspace_id.png?alt=media" alt="Workspace ID in the General tab"><figcaption></figcaption></figure>
   2. Generate a `workspace_api_key` in the **Security & API keys** tab, under **Stacksync Workspace API Key**: enter a key name and click **Generate new API key**. Copy the key, it is only shown once. **Only the owner** of the Stacksync workspace can generate workspace API keys.

      <figure><img src="https://1234677496-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F4zoaoqcTuhTKzdRmiB6e%2Fuploads%2Fgit-blob-0ab388d520d48273533042411c7307db1e1a309f%2Fokta_stacksync_workspace_api_key.png?alt=media" alt="Stacksync Workspace API Key in the Security &#x26; API keys tab"><figcaption></figcaption></figure>
3. Go back to your SAML app on the Provisioning page. Fill in the following parameter:
   1. **Base URL:** `https://api.stacksync.com/v1/workspaces/<your_stacksync_workspace_id>/scim/v2/`
   2. **API Token:** your `workspace_api_key`. Then click **Test API Credentials**. If the test fails, enter `Bearer <your_stacksync_workspace_api_key>` instead and test again.<br>

      <figure><img src="https://1234677496-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F4zoaoqcTuhTKzdRmiB6e%2Fuploads%2FGhiuQ81myvYWRGXq4Jmf%2Fimage.png?alt=media&amp;token=3a21599f-47dc-4e0e-838a-ad410efd657c" alt=""><figcaption></figcaption></figure>
4. Allow your SCIM app to create, update and deactivate users. Stacksync users never use passwords to connect to Stacksync therefore the `Sync Password` feature should be disabled.<br>

   <figure><img src="https://1234677496-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F4zoaoqcTuhTKzdRmiB6e%2Fuploads%2FxNG7T7yeR9biOvdv9OqD%2Fimage.png?alt=media&amp;token=6b87e98e-3f1a-4c0e-8c33-2d8097fcb867" alt=""><figcaption></figcaption></figure>
5. Go to the Profile Editor and add a new Attribute a new `roles`to the app. This is a standard SCIM attribute with the following fields:
   1. Data type: `string array`
   2. Display name: `roles`
   3. Variables name: `roles`
   4. External name: `roles`
   5. External namespace: `urn:ietf:params:scim:schemas:core:2.0:User`
   6. Description: `SCIM role attribute for Stacksync app`
   7. Enum: `true`
   8. Attribute member: `viewer` and `editor`
   9. Attribute required: `true`
   10. Attribute type: `Group`
   11. Group Priority: Use `Group Priority`<br>

       <figure><img src="https://1234677496-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F4zoaoqcTuhTKzdRmiB6e%2Fuploads%2FX8bgCtnH63pQFDU9xzsU%2Fimage.png?alt=media&amp;token=1831f884-b80a-4d06-8358-47e3211d3412" alt=""><figcaption></figcaption></figure>
6. Go to Directory/Groups, create 2 groups: `Stacksync Editors` and `Stacksync Viewers`. Each group will be assigned a different role in Stacksync (`editor` and `viewer`)<br>

   <figure><img src="https://1234677496-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F4zoaoqcTuhTKzdRmiB6e%2Fuploads%2FWzAuM8sqp4nOgLh0FvHJ%2Fimage.png?alt=media&amp;token=b50a93a5-1aea-4610-82e5-bfb36b452067" alt=""><figcaption></figcaption></figure>
7. Assign to the Stacksync Groups you just created the people you want to give access to Stacksync<br>

   <figure><img src="https://1234677496-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F4zoaoqcTuhTKzdRmiB6e%2Fuploads%2FINrMiTiuHgbTb7pFmxSG%2Fimage.png?alt=media&amp;token=2acbffe7-d0b0-45ff-833d-5fd3234926a0" alt=""><figcaption></figcaption></figure>
8. Go back to your application and under `Assignments` assign these 2 groups to the application. Make sure you select the right role for each group. You can ignore the other fields, Stacksync is not reading them.<br>

   <figure><img src="https://1234677496-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F4zoaoqcTuhTKzdRmiB6e%2Fuploads%2FSdyn10j8mRn4ty3nlVb6%2Fimage.png?alt=media&amp;token=26a0edf5-c6dd-43fb-9dc4-9f01465386ee" alt=""><figcaption></figcaption></figure>

That's it! 🎉