> For the complete documentation index, see [llms.txt](https://docs.seemoredata.io/external-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.seemoredata.io/external-docs/fundamentals/getting-set-up/authentication/setup-okta-sso.md).

# Setup Okta SSO

This integration enables authentication via **OpenID Connect (OIDC)** and automated user provisioning through **System for Cross-domain Identity Management (SCIM)**.

{% hint style="info" %}
**Required role to configure:** [Admin](/external-docs/fundamentals/settings/user-roles.md) or higher.

Users with lower roles can view this feature but cannot change its configuration.
{% endhint %}

***

### Overview

Seemore integrates with Okta using:

* **OIDC (OpenID Connect)** — user authentication
* **SCIM (System for Cross-domain Identity Management)** — automated user and role provisioning

This setup allows Okta administrators to:

* Manage Seemore users directly in Okta
* Assign and sync roles (*owner, admin, editor, viewer*)
* Map Okta groups to Seemore roles and sync them automatically
* Map Okta groups to Seemore [teams](/external-docs/fundamentals/settings/access-control/teams.md), which is what grants access to your accounts
* Automatically create or deactivate users

***

### Prerequisites

Before you start:

* Ensure you have **Admin rights** in both **Okta** and **Seemore**.
* Obtain from Seemore:
  * **SCIM base URL**
  * **Bearer token** (from *Integrations → SCIM Tokens*)
* Ensure each Okta user has a **unique External ID** for matching.
* Enable **SCIM provisioning** in your Seemore tenant.

{% hint style="info" %}
Seemore supports **Okta group synchronization**. Push your Okta groups to Seemore and map each group to the Seemore roles **and** the [teams](/external-docs/fundamentals/settings/access-control/teams.md) its members should get — both are applied automatically on the member's next login. See **Step 6** through **Step 8** below, and [Identity Provider Sync](/external-docs/fundamentals/settings/access-control/identity-provider-sync.md) for how the mappings behave day to day.
{% endhint %}

***

### Setup Steps

#### Step 1 — Create the Seemore App in Okta

1. In the **Okta Admin Console**, go to\
   `Applications → Applications → Create App Integration`.
2. Select:
   * **Sign-in method:** OIDC – OpenID Connect
   * **Application type:** Web Application
3. Configure:
   * **App name:** `Seemore`
   * **Login redirect URI:**

     ```
     https://auth.seemoredata.io/login/callback
     ```
4. Assign test users or groups to the app.

***

#### Step 2 — Configure OIDC in Seemore

1. In Seemore, open\
   `Settings → Preferences → Authentication → Okta`.<br>

   <figure><img src="https://3620459840-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FnSbIoBjUxWTGNWa9gGw7%2Fuploads%2FN5WXH0mHSLW3D1AfZ5CE%2Fimage.png?alt=media&amp;token=be7da5dc-00f9-458a-afd0-f7a5f29c94a3" alt=""><figcaption></figcaption></figure>
2. Enter:
   * **Okta domain** (from Okta)
   * **Client ID / Secret** (from the Okta app)<br>

     <figure><img src="https://3620459840-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FnSbIoBjUxWTGNWa9gGw7%2Fuploads%2FC94vaYeIFqa7elhdlEDS%2Fimage.png?alt=media&amp;token=e5c32ebd-8ee5-4bf0-8e0b-7217399e880e" alt=""><figcaption></figcaption></figure>
3. Save and test.\
   You should be redirected to Okta for sign-in and back to Seemore upon success.

***

#### Step 3 — Enable SCIM Provisioning in Seemore

1. Check the box to **Enable SCIM Provisioning** and save.<br>

   <div align="center" data-full-width="true"><figure><img src="https://3620459840-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FnSbIoBjUxWTGNWa9gGw7%2Fuploads%2F6AtvTnN2WfFgHRdvCFC8%2Fimage.png?alt=media&amp;token=5b9e2e50-25f8-4015-b77b-7c20d014fc21" alt=""><figcaption></figcaption></figure></div>
2. Click `Create Token`, then `Save` the generated token.\
   You won’t be able to view it again later.

<figure><img src="https://3620459840-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FnSbIoBjUxWTGNWa9gGw7%2Fuploads%2F6AtvTnN2WfFgHRdvCFC8%2Fimage.png?alt=media&amp;token=5b9e2e50-25f8-4015-b77b-7c20d014fc21" alt=""><figcaption></figcaption></figure>

<figure><img src="https://3620459840-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FnSbIoBjUxWTGNWa9gGw7%2Fuploads%2FF2ZFsIcXMi7oJqScrl0M%2Fimage.png?alt=media&amp;token=429d55d4-4676-4982-9454-dde5206c8aa9" alt=""><figcaption></figcaption></figure>

***

#### Step 4 — Enable SCIM Provisioning in Okta

1. Confirm that an **OpenID Connect** application has already been registered in the Okta Workforce tenant for OIDC-based authentication.
2. Confirm that your OpenID Connect application has **disabled Federation Broker Mode**.
3. Register a second application in Okta:
   * Go to `Applications → Applications → Create App Integration`
   * Choose **Secure Web Authentication**, then `Next`
4. On the **General App Settings** page:
   * Set a name and a URL
   * Select `Do not display application icon to users`
   * The URL entered is not used in the SCIM integration
5. Select `Finish`.
6. Navigate to the **General** tab → `Edit` → **Provisioning** section.
7. Choose `SCIM`, then `Save`.
8. Navigate to `Provisioning → Integration → Edit`, and configure the following:
   * **SCIM connector base URL:** SCIM Endpoint URL copied earlier
   * **Unique identifier field for users:** `userName`
   * Under **Supported provisioning actions**, enable:
     * Push New Users
     * Push Profile Updates
   * **Authentication Mode:** HTTP Header
   * Paste the token value into the `Authorization` field
   * (Optional) Test the connection, then choose `Save`.
9. Go to `Provisioning → Settings → To App → Edit`, then:
   * Enable `Create Users`, `Update User Attributes`, and `Deactivate Users`
   * Choose `Save`.
10. Under **Attribute Mappings**, se the **X** button to **delete** the following lines, which are not needed and may cause issues during PUT operations:

    | Attribute          | Value                                                                    |
    | ------------------ | ------------------------------------------------------------------------ |
    | Primary email type | `(user.email != null && user.email != '') ? 'work' : ‘'`                 |
    | Primary phone type | `(user.primaryPhone != null && user.primaryPhone != '') ? 'work' : ‘'`   |
    | Address type       | `(user.streetAddress != null && user.streetAddress != '') ? 'work' : ‘'` |

    Use the Attribute Mappings section to configure any additional SCIM attributes you want Okta WIC to send to your SCIM endpoint. If you add custom attributes, they must include a valid SCIM 2.0 external namespace property. For more information on external namespaces, read Okta's help section.

{% hint style="info" %}
You can now test user provisioning in the **Assignments** tab or test update operations by editing user attributes under **Directory → People** in Okta.
{% endhint %}

***

#### Step 5 — Map User Attributes

Go to `Provisioning → To App → Mappings` and configure the below fields:

Add a custom property named `externalId` to link Okta users with Seemore users.

<table><thead><tr><th width="374">Property</th><th>Value</th></tr></thead><tbody><tr><td>External name</td><td>externalId</td></tr><tr><td>External namespace</td><td>urn:ietf:params:scim:schemas:core:2.0:User</td></tr><tr><td>Data type</td><td>string</td></tr></tbody></table>

<table><thead><tr><th width="294.33203125">Okta Attribute</th><th>Seemore Attribute</th><th>Description</th></tr></thead><tbody><tr><td><code>user.getInternalProperty("id")</code></td><td><code>user:external_id</code></td><td>Correlation ID between Okta and Seemore</td></tr><tr><td><code>user.email</code></td><td><code>user:email</code></td><td>Primary email address</td></tr></tbody></table>

{% hint style="warning" %}
💡 **Important:**\
The key linking attribute is `external_id` under the namespace `user`.\
This must correspond to Seemore’s internal user ID for proper linking.
{% endhint %}

***

#### Step 6 — Push Okta groups to Seemore

Seemore can assign roles based on the Okta groups a user belongs to. First, tell Okta which groups to send:

1. In the Okta **Seemore (SCIM)** application, open the **Push Groups** tab.
2. Choose **Push Groups → Find groups by name** (or **by rule**) and add the groups whose members should receive Seemore roles.
3. Save. Okta pushes the selected group definitions — and their memberships — to Seemore.

{% hint style="info" %}
Only the groups you explicitly push appear in Seemore. After the first push, Okta keeps membership in sync automatically; changes take effect on each user's **next login**.
{% endhint %}

#### Step 7 — Assign Seemore roles to your groups

Once your groups are pushed, map each one to the Seemore roles its members should receive.

{% hint style="warning" %}
Any **Admin** can assign the `admin`, `editor`, and `viewer` roles. Only an **Owner** can grant or remove the **Owner** role on a group.
{% endhint %}

1. In Seemore, open `Settings → Preferences → Authentication → Okta` and make sure **Enable SCIM Provisioning** is on.
2. Find the **Group → role assignment** section. The groups you pushed from Okta appear here.\
   If a group is missing, confirm it is selected under **Push Groups** in Okta, then refresh the page.
3. For each group, select one or more roles: `owner`, `admin`, `editor`, or `viewer`.
4. Click **Save roles**.

<figure><img src="https://3620459840-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FnSbIoBjUxWTGNWa9gGw7%2Fuploads%2Fgit-blob-22e7ff557578671a9f01fd43a48499e4994cd967%2Fscim-group-roles.png?alt=media" alt="The Group → role assignment section of an Okta connection"><figcaption><p>Each pushed Okta group is mapped to the Seemore roles its members receive.</p></figcaption></figure>

**How role resolution works**

* A user receives the **combined roles of every group** they belong to.
* Roles are applied on the user's **next login** — assign or change them before the user signs in again.
* Group membership is authoritative: on each login, a user's `owner`/`admin`/`editor`/`viewer` roles are reconciled to match the roles their groups grant. Removing a role from a group — or removing the user from the group — revokes that role on the user's next login.

<details>

<summary>Alternative: send roles as a per-user SCIM attribute</summary>

Instead of mapping groups, you can send Seemore roles directly on each user as a multi-value SCIM attribute named `roles`.

In Okta:

1. Edit the Seemore app’s schema by adding a custom attribute:
   * **Name:** `roles`
   * **External name:** `user:roles`
   * **Type:** Array
2. Map the Okta role or group to this attribute:
   * **Okta source:** `user.role` (or your internal role field)
   * **Target:** `roles`
3. Allowed values:
   * `owner`
   * `admin`
   * `editor`
   * `viewer`

> ⚙️ **Technical Note:**\
> The SCIM spec requires this field to be an array (e.g., `[{`type`:"XXX", value: "admin"}]`), not a single string.

</details>

#### Step 8 — Assign Seemore teams to your groups

Groups can also drive [team](/external-docs/fundamentals/settings/access-control/teams.md) membership, which is what grants access to your accounts. Create the teams in Seemore first, then map each group to the teams its members should join.

1. In the same **SCIM** step, find the **Group → team assignment** section, just below **Group → role assignment**.
2. For each group, select one or more Seemore teams.
3. Click **Save teams**.

<figure><img src="https://3620459840-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FnSbIoBjUxWTGNWa9gGw7%2Fuploads%2Fgit-blob-c63db2a63091ff47cca3e281ea30062e222f0010%2Fscim-group-teams.png?alt=media" alt="The Group → team assignment section of an Okta connection"><figcaption><p>Each pushed Okta group is mapped to the Seemore teams its members join.</p></figcaption></figure>

**How team membership works**

* Members join and leave the mapped teams as their Okta group membership changes, applied on their **next login**.
* **Only mapped teams are managed.** A Seemore team that no group points at keeps the membership you manage manually.
* Because a team carries [asset groups](/external-docs/fundamentals/settings/access-control/asset-groups.md), mapping a group to a team is what actually grants data access — set the team's access up before mapping to it.

See [Identity Provider Sync](/external-docs/fundamentals/settings/access-control/identity-provider-sync.md) for the full behavior, including a worked example.

#### Step 9 — Provision and Test

1. Assign a test user in Okta to the Seemore app and to at least one pushed group.
2. Verify in Seemore:
   * User appears under **Settings → Access control → Users**
   * External ID and email are correct
   * Role and team membership sync upon the user's first login (session-level binding)

***

### Troubleshooting

| Symptom                         | Cause                                                               | Resolution                                                                                       |
| ------------------------------- | ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
| User not created                | Invalid SCIM credentials                                            | Check API token and Base URL                                                                     |
| Duplicate users                 | `external_id` mismatch                                              | Ensure `user:external_id` is unique                                                              |
| Roles missing                   | Sent as string                                                      | Change to array type                                                                             |
| Role not visible post-provision | Role applies at session level                                       | User must re-login                                                                               |
| Group not listed in Seemore     | Group not pushed from Okta                                          | Add the group under **Push Groups** in Okta, then refresh the settings page                      |
| Group roles not applied         | User has not logged in since the change                             | Group roles apply on the next login — have the user sign in again                                |
| Group teams not applied         | User has not logged in since the change, or the team was not mapped | Team membership applies on the next login; confirm the mapping under **Group → team assignment** |
| Team missing from the team list | The team does not exist in Seemore yet                              | Create it under **Settings → Access control → Teams**, then reopen the connection                |

***

### Validation Checklist

✅ SCIM connection tested successfully\
✅ User created in Seemore after Okta push\
✅ Pushed Okta groups appear in the **Group → role assignment** section\
✅ Each group is mapped to the intended Seemore role(s)\
✅ Each group is mapped to the intended Seemore team(s)\
✅ Role appears correctly after login\
✅ External ID matches Seemore internal ID

***

### Related Resources

* [Identity Provider Sync](/external-docs/fundamentals/settings/access-control/identity-provider-sync.md) — how group-to-role and group-to-team mappings behave day to day
* [Access Control](/external-docs/fundamentals/settings/access-control.md) — users, teams, and asset groups in Seemore
* [Okta SCIM Integration Guide](https://developer.okta.com/docs/reference/scim/)
* [OIDC setup with Okta](https://developer.okta.com/docs/guides/implement-auth-code/)
* [Okta SCIM provisioning](https://developer.okta.com/docs/guides/scim-provisioning-integration-connect/main/#create-your-private-integration-in-okta)