# OKTA

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

This setup takes \~10 minutes.
{% endhint %}

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

Notes:

* This setup must be implemented by an Okta **admin**.
* The SCIM integration is associated with a unique Stacksync workspace. If you have multiple workspaces (such as dev, staging, and prod), you will need to set up an SCIM app for each workspace. Each workspace has independent RBAC enforcement.

## SSO (SAML) setup instructions

1. On your Okta homepage, go to the admin section.

   <figure><img src="/files/xN9eLTzn0jloBFs5zJVW" alt=""><figcaption></figcaption></figure>
2. In the Applications section, create an app integration of type SAML 2.0.

   <figure><img src="/files/tih1P6Il02CXPO4JciyE" alt=""><figcaption></figcaption></figure>

   <figure><img src="/files/oyWJfx5Pqu3QsgCYbkoT" alt=""><figcaption></figcaption></figure>
3. Set the app name to `Stacksync`. You can also add the Stacksync app logo (download the file below).

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

4. Configure your SAML settings with:
   1. Single sign-on URL: `https://auth.stacksync.com/login/callback?connection=<sso_id_provided_by_stacksync_team_for_you>`
   2. Audience URI: `urn:auth0:stacksync:<sso_id_provided_by_stacksync_team_for_you>`
   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="/files/JeIaiBPOLK2S5iEQmwjx" alt=""><figcaption></figcaption></figure>
   6. You can skip the `Feedback` section and click `Finish`
      1. Send the following details to `sso@stacksync.com`:

         1. `Identity Provider Single Sign-On URL` at the top of the SAML setup instructions page.<br>

            <figure><img src="/files/lVVvirKrkGnDJUMsCahn" alt=""><figcaption></figcaption></figure>

         <figure><img src="/files/9EX3ZNvlAebyS2rGXOLA" alt=""><figcaption></figcaption></figure>

         `2. SAML Signing Certificates` for `SHA2`

         <figure><img src="/files/Xt25tilKhjkpyXjiMGTK" alt=""><figcaption></figcaption></figure>

         1. Once we have received the above information, we will activate SSO and you’re all set!

## SCIM setup instructions

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

   <figure><img src="/files/GakLQXACy0auZ3KKispn" alt=""><figcaption></figcaption></figure>
2. Go to the Stacksync Workspace Settings page at `https://app.stacksync.com` to find the information needed for the next steps.
   1. Find your Stacksync `workspace_id` on top of the page.

      <figure><img src="/files/vXT77YJc7Qrg1SHOyvvp" alt=""><figcaption></figcaption></figure>
   2. Generate a `workspace_api_key` at the bottom of the same page. **Only the owner** of the Stacksync workspace can create workspace API keys.

      <figure><img src="/files/qm9NhubWnZHosIa2dfoO" alt=""><figcaption></figcaption></figure>
3. Go back to your SAML app on the Provisioning page. Fill in the following parameters:
   1. **Base URL:** `https://api.stacksync.com/v1/workspaces/<your_stacksync_workspace_id>/scim/v2/`
   2. **API Token:** `Bearer <your_stacksync_workspace_api_key>`<br>

      <figure><img src="/files/QIdVHJCX7Gl7Z9Wnfd7c" 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="/files/dRH1MkJNrSgGDV9YSNNK" alt=""><figcaption></figcaption></figure>
5. Go to the Profile Editor and add a new attribute `roles` to the app. This is a standard SCIM attribute with the following fields:
   1. Data type: `string array`
   2. Display name: `roles`
   3. Variable 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="/files/lkW0kbyMcbadHuNOrhjn" alt=""><figcaption></figcaption></figure>
6. Go to Directory/Groups and create two groups: `Stacksync Editors` and `Stacksync Viewers`. Each group will be assigned a different role in Stacksync (`editor` and `viewer`).<br>

   <figure><img src="/files/4e9aH8G44hUg0nGQuqoj" alt=""><figcaption></figcaption></figure>
7. Assign the people you want to give access to Stacksync to the Stacksync groups you just created.<br>

   <figure><img src="/files/kKC42TJPDMQ06YXqCGkm" alt=""><figcaption></figcaption></figure>
8. Go back to your application and, under `Assignments`, assign these two groups to the application. Make sure you select the right role for each group. You can ignore the other fields. Stacksync does not read them.<br>

   <figure><img src="/files/D5Wm902nonqyKwj0k3C7" alt=""><figcaption></figcaption></figure>

That's it! 🎉


---

# 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/authentication/security/sso/okta.md?ask=<question>
```

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.