Okta SCIM Setup Guide

​

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 instead.
• A Genesis SCIM bearer token generated from the SCIM Admin API.
• A Genesis group-to-role mapping for every Okta group you plan to push. See 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

​

Genesis setup

1. Confirm SCIM environment configuration is present on the Genesis deployment. At minimum, production deployments usually set:
   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:
   POST /api/config/scim/tokens/rotate
   
   Save the returned plaintext token immediately. Genesis returns it only once.
3. Configure group-to-role mapping:
   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:
   curl -H "Authorization: Bearer <SCIM token>" \
     https://<genesis-host>/scim/v2/ResourceTypes
   

​

Okta setup

1

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.

2

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.

3

Open Provisioning and configure API integration

Open the app’s Provisioning tab, then choose Configure API Integration.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.

4

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.

5

Verify attribute mappings

Confirm Okta maps the user profile fields Genesis persists:Use the mapping table below as the customer-facing baseline.

6

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.

​

Recommended attribute mappings

urn:ietf:params:scim:schemas:extension:enterprise:2.0:User

​

Verification

• 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.

curl -H "Authorization: Bearer <SCIM token>" \
  "https://<genesis-host>/scim/v2/Users?filter=userName%20eq%20%[email protected]%22"

{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User",
    "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"
  ],
  "userName": "[email protected]",
  "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"
  }
}

​

Unsupported and extra fields

​

Troubleshooting

​

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.