> ## Documentation Index
> Fetch the complete documentation index at: https://docs.genesiscomputing.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Okta SCIM Setup Guide

> End-to-end Okta setup for inbound SCIM provisioning into Genesis.

Use this guide to configure Okta to push users and groups into Genesis through
the Genesis SCIM 2.0 service-provider endpoint.

The screenshots below were captured from a real lab setup on May 15, 2026. They
show a temporary lab hostname. For a customer rollout, replace that host with
the customer's Genesis hostname.

## Prerequisites

* Okta administrator access with permission to create and configure
  applications.
* A public HTTPS Genesis hostname reachable from Okta. If Genesis runs on a private
  network Okta cannot reach, use the [Okta directory sync](/docs/Setup/Okta-Directory-Sync)
  instead.
* A Genesis SCIM bearer token generated from the
  [SCIM Admin API](/docs/Setup/SCIM-Admin-API#rotate-a-bearer-token).
* A Genesis group-to-role mapping for every Okta group you plan to push. See
  [Configure the group-to-role mapping](/docs/Setup/SCIM-Admin-API#configure-the-group-to-role-mapping).
* `GENESIS_SCIM_REQUIRE_PROVISIONED_USERS=false` during the pilot. Enable the
  login gate only after pilot users are provisioned and verified.

## Values to collect

| Setting | Value |
| - | - |
| SCIM base URL | `https://<genesis-host>/scim/v2` |
| Auth type | Bearer token |
| User identifier | `userName`, normally the primary email address |
| Provisioning operations | Create users, update user attributes, deactivate users |
| Group push | Only groups present in the Genesis group-to-role mapping |

<Warning>
  Treat the SCIM bearer token like a password. Do not put the plaintext token in
  screenshots, tickets, Slack, email, or shell history.
</Warning>

## Genesis setup

1. Confirm SCIM environment configuration is present on the Genesis deployment.
   At minimum, production deployments usually set:

   ```text theme={null}
   GENESIS_SCIM_BEARER_TOKEN=<generated-scim-token>
   GENESIS_SCIM_GROUP_ROLE_MAPPING={"company-admins":"admin","company-users":"user"}
   GENESIS_SCIM_REQUIRE_PROVISIONED_USERS=false
   GENESIS_SCIM_RATE_LIMIT_PER_MINUTE=600
   GENESIS_SCIM_TENANT_ID=default
   ```

2. Rotate or create the SCIM bearer token:

   ```http theme={null}
   POST /api/config/scim/tokens/rotate
   ```

   Save the returned plaintext token immediately. Genesis returns it only once.

3. Configure group-to-role mapping:

   ```http theme={null}
   PUT /api/config/scim/group-role-mapping
   Content-Type: application/json

   {
     "group_role_mapping": {
       "company-admins": "admin",
       "company-users": "user"
     }
   }
   ```

4. Confirm the public SCIM endpoint responds:

   ```bash theme={null}
   curl -H "Authorization: Bearer <SCIM token>" \
     https://<genesis-host>/scim/v2/ResourceTypes
   ```

## Okta setup

<Steps>
  <Step title="Create the Okta SCIM app">
    In the Okta Admin Console, open **Applications** and add the catalog app
    **SCIM 2.0 Test App (OAuth Bearer Token)**. Name it something recognizable,
    such as `Genesis SCIM`.

    <img src="https://mintcdn.com/genesiscomputing/veD1H6lmZZSkMTgm/images/scim-okta-applications.png?fit=max&auto=format&n=veD1H6lmZZSkMTgm&q=85&s=36ae285132bcfb955ad792cceee88274" alt="Okta applications list with the SCIM test app available." width="1920" height="936" data-path="images/scim-okta-applications.png" />
  </Step>

  <Step title="Complete required Sign On placeholders">
    Okta's SCIM test app may require sign-on fields even when you are only
    using it for SCIM provisioning. These are not the SCIM endpoint values.

    Use the customer's Genesis host for the base audience value. If SAML sign-on
    is not part of this rollout, use placeholder values that Okta accepts for
    the required fields, or use the customer's actual SSO values if they have
    already configured them.

    <img src="https://mintcdn.com/genesiscomputing/veD1H6lmZZSkMTgm/images/scim-okta-signon.png?fit=max&auto=format&n=veD1H6lmZZSkMTgm&q=85&s=4457886c8be7f56da9c46ff85b7d666f" alt="Okta Sign On settings for the SCIM test app." width="1920" height="936" data-path="images/scim-okta-signon.png" />
  </Step>

  <Step title="Open Provisioning and configure API integration">
    Open the app's **Provisioning** tab, then choose **Configure API
    Integration**.

    <img src="https://mintcdn.com/genesiscomputing/veD1H6lmZZSkMTgm/images/scim-okta-provisioning-initial.png?fit=max&auto=format&n=veD1H6lmZZSkMTgm&q=85&s=60cfaffe4c82e2ad5113fe56667f83e0" alt="Okta Provisioning tab before API integration is enabled." width="1920" height="936" data-path="images/scim-okta-provisioning-initial.png" />

    Configure:

    * **SCIM connector base URL:** `https://<genesis-host>/scim/v2`
    * **Unique identifier field for users:** `userName`
    * **Authentication mode:** HTTP Header or OAuth Bearer Token, depending on
      the Okta app template wording.
    * **Bearer token:** the Genesis SCIM token.

    Click **Test API Credentials** and continue only after Okta confirms the
    credentials are valid.
  </Step>

  <Step title="Enable To App provisioning operations">
    Under **Provisioning -> To App**, enable:

    * **Create Users**
    * **Update User Attributes**
    * **Deactivate Users**

    Leave **Sync Password** disabled unless a customer explicitly needs password
    provisioning and Genesis has been configured to accept it. The normal
    Genesis SCIM flow does not need Okta to sync passwords.

    <img src="https://mintcdn.com/genesiscomputing/veD1H6lmZZSkMTgm/images/scim-okta-provisioning-enabled.png?fit=max&auto=format&n=veD1H6lmZZSkMTgm&q=85&s=5606bc900fda9f4b2accfba2a2939de7" alt="Okta To App provisioning settings enabled for create, update, and deactivate." width="1920" height="936" data-path="images/scim-okta-provisioning-enabled.png" />
  </Step>

  <Step title="Verify attribute mappings">
    Confirm Okta maps the user profile fields Genesis persists:

    <img src="https://mintcdn.com/genesiscomputing/veD1H6lmZZSkMTgm/images/scim-okta-attribute-mappings.jpg?fit=max&auto=format&n=veD1H6lmZZSkMTgm&q=85&s=f1be70a78375dcbaac5bb387b6725045" alt="Okta attribute mappings for given name, family name, title, display name, employee number, division, and department." width="1096" height="886" data-path="images/scim-okta-attribute-mappings.jpg" />

    Use the mapping table below as the customer-facing baseline.
  </Step>

  <Step title="Assign pilot users and groups">
    Assign one pilot user first. Okta should create the Genesis SCIM user when
    the app assignment is saved.

    Then push only the Okta groups that are present in the Genesis
    group-to-role mapping. Unmapped groups are rejected so that accidental group
    pushes do not grant unexpected access.
  </Step>
</Steps>

### Recommended attribute mappings

| SCIM attribute | Okta source |
| - | - |
| `userName` | Okta username or primary email |
| `emails[primary].value` | `user.email` |
| `displayName` | `user.displayName` |
| `name.givenName` | `user.firstName` |
| `name.familyName` | `user.lastName` |
| `title` | `user.title` |
| Enterprise `employeeNumber` | `user.employeeNumber` |
| Enterprise `division` | `user.division` |
| Enterprise `department` | `user.department` |

`employeeNumber`, `division`, and `department` are optional. Okta sends them
under the SCIM Enterprise User extension namespace:

```text theme={null}
urn:ietf:params:scim:schemas:extension:enterprise:2.0:User
```

## Verification

After assigning a pilot user, verify both sides.

In Okta:

* The app assignment is active for the pilot user.
* The Provisioning logs show a successful create or update.
* **Force Sync** succeeds after changing one mapped attribute such as display
  name or title.

In Genesis:

```bash theme={null}
curl -H "Authorization: Bearer <SCIM token>" \
  "https://<genesis-host>/scim/v2/Users?filter=userName%20eq%20%22alice@example.com%22"
```

For a user with Enterprise fields, the returned resource should include both
the core User schema and the Enterprise User extension schema:

```json theme={null}
{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User",
    "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"
  ],
  "userName": "alice@example.com",
  "displayName": "Alice Example",
  "name": {
    "givenName": "Alice",
    "familyName": "Example"
  },
  "title": "Integration Analyst",
  "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
    "employeeNumber": "A-100",
    "division": "Client Success",
    "department": "Customer Engineering"
  }
}
```

The May 15, 2026 Okta lab verified create and update flows for
`displayName`, `name.givenName`, `name.familyName`, `title`, and the Enterprise
extension fields above.

## Unsupported and extra fields

Genesis persists the fields listed in this guide. Extra top-level fields in a
SCIM create or replace request are ignored by the API schema.

SCIM PATCH operations are stricter. If Okta sends a populated custom or default
mapping that Genesis does not support as a PATCH path, Genesis can reject that
specific update with a SCIM-shaped `400`. For production setups, keep the Okta
mappings focused on the fields Genesis persists, or validate any additional
mappings during the pilot before broad rollout.

## Troubleshooting

| Symptom | Check |
| - | - |
| Okta credential test returns `401` or `403` | Confirm the bearer token was copied exactly and has not been revoked. |
| Okta credential test cannot connect | Confirm the base URL includes `/scim/v2`, the Genesis hostname is public HTTPS, and `/ResourceTypes` responds with the same token. |
| User is created but names are missing | Confirm `givenName`, `familyName`, and `displayName` mappings are set to **Create and update**, then use **Force Sync**. |
| Enterprise fields are missing | Confirm Okta maps `employeeNumber`, `division`, and `department`, and that Genesis is running a build that supports the SCIM Enterprise User namespace. |
| Group push returns `400` | Add the Okta group display name or external ID to the Genesis group-to-role mapping, or stop pushing that group. |
| Login rejected after SSO succeeds | Keep `GENESIS_SCIM_REQUIRE_PROVISIONED_USERS=false` during setup. Enable it only after the user exists in Genesis with `active=true`. |

## Handoff checklist

* Genesis SCIM base URL provided to the customer.
* SCIM bearer token delivered through a secure channel.
* Group-to-role mapping agreed and configured.
* Okta app credential test passed.
* One pilot user created from Okta and visible in Genesis.
* One mapped attribute update synced from Okta to Genesis.
* One mapped group push granted the expected Genesis role.
* One user deactivation set `active=false` in Genesis.
* SCIM-only login admission enabled only after pilot validation.