> For the complete documentation index, see [llms.txt](https://docs.natoma.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.natoma.ai/docs/enterprise/secure-access-to-natoma/okta-scim-groups.md).

# Manage Natoma Role from Okta

This guide covers how to configure SCIM attribute mapping and group rules to provision users with the correct Natoma roles from Okta.

{% hint style="info" %}
OIN SAML/SCIM setup must be completed before following this guide. See [Okta SSO](/docs/enterprise/secure-access-to-natoma/okta-sso.md) for setup instructions.
{% endhint %}

***

## Step 1 — Verify or Add the `appuser.role` Attribute

### OIN App Users

{% hint style="info" %}
The `appuser.role` attribute should already exist for OIN app users. Verify it is present and skip to Step 2.
{% endhint %}

1. In Okta Admin, go to **Applications** and open the Natoma app.
2. Click the **Provisioning** tab, then **Go to Profile Editor**.
3. Confirm that `appuser.role` appears in the attribute list.

If it is missing, contact Natoma support — it should be present by default on the OIN app.

### Custom App Users

1. In Okta Admin, go to **Applications** and open your custom Natoma app.
2. Click the **Provisioning** tab > **Go to Profile Editor**.
3. Click **+ Add Attribute** and configure it with the following settings:

| Field              | Value                                        |
| ------------------ | -------------------------------------------- |
| Display name       | `role`                                       |
| Variable name      | `role`                                       |
| External name      | `role`                                       |
| External namespace | `urn:ietf:params:scim:schemas:core:2.0:User` |
| Attribute type     | `GROUP`                                      |

4. Check the box to **define a list of Role Values** and add the following:
   * `Admin`
   * `AppAdmin`
   * `Member`

{% hint style="info" %}
Setting **Attribute Type** to `GROUP` allows the attribute to be overridden at the group app assignment level.
{% endhint %}

***

## Step 2 — Assign the Natoma App to an Okta Group

Assign the Natoma app to each Okta group you want to use for role provisioning.

1. In Okta Admin, open the Natoma app and go to the **Assignments** tab.
2. Click **Assign > Assign to Groups**.
3. Search for and select the group (e.g., `Natoma Test - Admins`).
4. Click **Assign**, then **Done**.

***

## Step 3 — Set the Role Value on the Group Assignment

After assigning the app to a group, set the value of `appuser.role` for that group. This value will be applied to all users in the group when they are provisioned to Natoma.

1. In the Natoma app, go to **Assignments**.
2. Find the group in the list and click the **edit** (pencil) icon.
3. In the group assignment dialog, locate the **Role** attribute field.
4. Enter the Natoma role value — `admin`, `AppAdmin`, or `member`.
5. Click **Save**.

***

## Step 4 — Configure the Okta to Natoma Profile Mapping

Verify the attribute mapping is configured so that the `appuser.role` value is passed through to Natoma during provisioning.

1. In the Natoma app, go to **Provisioning > To App**.
2. Confirm that **Role** is set to **Map from Okta Profile** (or is included in the attribute list).
3. Verify the mapping expression references `appuser.role`.
4. Click **Save** if any changes were made.

***

## Step 5 — Test the Configuration

1. Add a test user to one of the Okta groups configured above.
2. In Okta, push or provision the user to Natoma (or wait for the next sync).
3. In Natoma, confirm the user appears with the correct role.

{% hint style="warning" %}
If roles are not populating correctly, confirm that the `appuser.role` attribute type is set to `GROUP` and that the mapping in Step 4 is saved.
{% endhint %}