Configure production SCIM 2.0 provisioning for Trustmi using the approved Okta application or a manually configured connector in another identity platform. SCIM manages user accounts and organizational-unit membership. Roles and permissions are managed separately in Trustmi.
The production SCIM base URL is https://api.trustmi.ai/scim/v2. Choose one provisioning platform to manage the agreed users and OUs. Configure Single Sign-On (SSO) separately; continue using your existing sign-in configuration. For Okta SSO, see Configure Okta OIDC Single Sign-On for Trustmi, subject to availability of the OIDC-enabled application version.
- Prepare SCIM access in Trustmi
- Configure the approved Okta application (video)
- Configure SCIM manually for another identity provider (video)
Prerequisites
- Administrator access to the identity platform that will manage provisioning. For Okta, permission to manage applications and provisioning is required.
- A Trustmi administrator account for the intended organization, with access to Settings → Identity & Provisioning → SCIM Provisioning (or Settings → Authentication → SCIM Provisioning in the earlier settings layout) and permission to manage SCIM tokens. Contact Trustmi Support if the page or token controls are unavailable.
- SCIM provisioning enabled for that Trustmi organization and its full SCIM bearer-token secret.
- A dedicated test user for initial validation.
Supported Features
The following features describe the Okta configuration. For other providers, review the supported API operations in the manual configuration section and validate your connector before expanding provisioning.
| Feature | Support and behavior |
|---|---|
| Create users — Okta → Trustmi | Create an account when a user is assigned to the application. |
| Update user attributes — Okta → Trustmi | Update first name, last name, title, department, and division. See identity-update restrictions below. |
| Deactivate users — Okta → Trustmi | Mark the Trustmi account inactive when the user is unassigned or deactivated in Okta. |
| Reactivate users — Okta → Trustmi | Reactivate an existing account when reassigned in Okta. |
| Import new users — Trustmi → Okta | Import eligible users from the connected Trustmi organization for review and matching in Okta. Review and confirm imports before creating or assigning Okta users. |
| Import Profile Updates — Trustmi → Okta | Import refreshes the supported profile values in Okta's application import data. Automatic updates to the main Okta user profile are not supported by the configuration described here; Okta remains the profile source. Contact Trustmi Support before configuring Trustmi as a profile source. |
| Group Push and group import | Group Push creates and renames Trustmi organizational units, synchronizes memberships, and supports soft deletion. Import Groups reads groups and their memberships from Trustmi into Okta when enabled. |
| Password synchronization | Not supported. |
| User schema import | Not included. Use the documented profile attributes and mappings. |
Import new users and Import Profile Updates are separate from user schema import. Importing a user does not configure SSO or select that user's Trustmi permissions and organizational-unit access.
Prepare Trustmi and Configure Okta
Video: Configure SCIM through the Okta application
Download MP4 · Read the transcript
1. Prepare SCIM access in Trustmi
- Sign in to Trustmi production, select the intended organization, and open Settings → Identity & Provisioning → SCIM Provisioning (or Settings → Authentication → SCIM Provisioning in the earlier settings layout).
- Enable SCIM provisioning if it is not already enabled.
- Copy the Endpoint URL shown on the page and confirm it is
https://api.trustmi.ai/scim/v2. Do not append an organization ID,/Usersor/Groups, and do not use your SSO URL. If the displayed endpoint differs, contact Trustmi Support before proceeding. - If no active token exists, select Create Token. Copy the full secret immediately and store it in your organization's approved secrets manager.
The Token ID is metadata and cannot authenticate the integration. The full secret is shown only once. Use a Trustmi-issued production SCIM token for this organization, not an Okta API token, Portal session token or SSO client secret. If a token is already active, coordinate with its owner before replacing it. Creating a replacement invalidates the previous token; there is no overlapping-token rotation window. Update the connector as part of the same change.
2. Add the approved Okta application and verify usernames
- In the Okta Admin Console, open Applications → Applications → Browse App Catalog and add the approved Trustmi integration. For an existing application, confirm that a Provisioning tab is available before proceeding.
- If the Trustmi integration or Provisioning tab is unavailable, contact Trustmi Support to confirm the installed application version and provisioning availability.
- For the SCIM-only version, SCIM
userNamecomes from the Okta username (user.login); that version has no Sign On tab or Application username format selector. In an OIDC-enabled version with Sign On settings, review the configured application username. OIDC availability and SSO configuration are separate from enabling SCIM. - For initial onboarding, use the intended Trustmi/SSO email for both the application username and primary email. For the SCIM-only version, verify
user.loginanduser.emailbefore assignment. If your organization requires distinct values, contact Trustmi Support to agree the connector mapping. Do not change an existing corporate login solely for provisioning.
Trustmi supports a distinct external SCIM userName and a valid primary account email. Using the same intended Trustmi/SSO email for both is the recommended initial mapping, rather than a universal API requirement. Trustmi sign-in continues to use the account email. Username/email changes are not supported through User PATCH.
3. Configure API access
- Open Provisioning → Integration → Configure API Integration.
- Enable API integration.
- Paste the full SCIM token copied from Trustmi into API Token, without adding
Bearer. If a base-URL field is displayed, enterhttps://api.trustmi.ai/scim/v2. - Select Test API Credentials and resolve any errors.
- Enable Import Groups if you need to import Trustmi groups and memberships into Okta. Review the intended organization and settings, then select Save.
A successful credential test verifies connectivity and authentication. Validate the user lifecycle separately.
4. Enable provisioning and check the profile
Under Provisioning → To App → Edit, enable Create Users, Update User Attributes, and Deactivate Users. Leave password synchronization disabled. Turn off Set password when creating new users and Sync Password if those options are offered.
Use these application-profile mappings:
| Okta application attribute | Okta source | SCIM attribute |
|---|---|---|
userName |
user.login (fixed for SCIM-only integrations) |
userName |
givenName |
user.firstName |
name.givenName |
familyName |
user.lastName |
name.familyName |
email |
user.email |
Primary emails.value; use the intended Trustmi/SSO email
|
title |
user.title |
title |
department |
user.department |
Enterprise User extension department
|
division |
user.division |
Enterprise User extension division
|
The Enterprise User extension is urn:ietf:params:scim:schemas:extension:enterprise:2.0:User. Title, department, and division are optional. The active value is controlled by provisioning and deactivation; do not add a separate profile mapping for it.
Configure only the documented profile attributes. Department and division are profile fields; they do not create or assign an organizational unit, and a missing department does not trigger a global-OU fallback. Manage OU membership through SCIM Groups.
5. Review import settings
- Open Provisioning → To Okta to review import matching and scheduling.
- For initial validation, use manual imports and leave automatic confirmation and activation disabled.
- Open Import → Import Now and review the imported users.
- Match existing users by email and confirm only the intended records. Do not confirm every imported user without review.
- Keep Okta as the profile source for this configuration. Imported profile values do not automatically update the main Okta user profile. Contact Trustmi Support if you need Trustmi to act as a profile source; enabling profile sourcing changes which system controls user profiles.
6. Validate with a dedicated test user
- Assign the test user to the application and confirm their email and profile in Trustmi User Management.
- Update the test user's first or last name in Okta and confirm the change in Trustmi.
- Verify Trustmi permissions and organizational-unit access separately.
- Unassign or deactivate the test user and confirm the Trustmi account becomes inactive.
- Reassign the same identity and verify reactivation. Review Okta provisioning tasks and the System Log before expanding the rollout.
7. Configure and validate groups
A SCIM group corresponds to a Trustmi organizational unit. Group membership affects organizational-unit access scope; roles and permissions are managed separately.
- Assign intended test users to the application first. Use individual assignment or a separate assignment group; do not use the same group for application assignment and Group Push.
- Open Push Groups → Push Groups → Find groups by name. Select a dedicated test group, choose Create Group, and save.
- Verify Active status and the matching organizational unit in the intended Trustmi organization. Add and remove a test member, then rename the group and verify each change in Trustmi.
- To delete the target group, choose Unlink pushed group → Delete the group in the target app. Trustmi deactivates the organizational unit and hides it from SCIM. User accounts are not deleted. Choose Leave the group only when you intend to retain it.
- For inbound synchronization, enable Import Groups under Provisioning → Integration, run a manual import, and review groups and memberships. Review user matching separately; do not automatically confirm or activate all imported users.
If membership does not synchronize, confirm that the user is assigned and provisioned in this application and organization. Check Push Groups errors and the Okta System Log. Do not link or delete an existing organizational unit solely for testing.
Configure SCIM Manually for Other Identity Providers
Complete Prepare SCIM access in Trustmi first, then create a SCIM 2.0 connector in your identity platform. The connector can communicate directly with Trustmi; an Okta intermediary is not required by the Trustmi API. Validate the specific product, connector version and generated requests before enabling wider provisioning.
Video: Configure SCIM with another identity provider
Download MP4 · Read the transcript
1. Configure the connection
| Setting | Value |
|---|---|
| SCIM base URL | https://api.trustmi.ai/scim/v2 |
| Authentication | Bearer token / API Token |
| Credential | Your organization's Trustmi-issued production SCIM token |
| Users / Groups resources |
/Users and /Groups
|
| Accept / JSON content type | application/scim+json |
| Persistent correlation key | Trustmi's returned SCIM id for each User or Group |
| Pagination | One-based startIndex; request count of at most 100
|
| Password and role synchronization | Disabled |
The token identifies your organization; do not append an organization ID or resource path to the base URL. Keep HTTPS certificate verification enabled. No OAuth authorization URL, token URL or client-credentials exchange is required.
In an API Token or Bearer Token field, enter only the secret and let the connector construct the header. If it accepts a complete Authorization header instead, supply Bearer followed by one space and the token exactly once:
Authorization: Bearer <TRUSTMI_SCIM_TOKEN>
Accept: application/scim+json
Content-Type: application/scim+json
The Content-Type header applies to requests with a JSON body. Store the credential in protected connector storage; never include it in tickets or shared request examples.
2. Validate discovery and mapping
Send authenticated GET requests to /ServiceProviderConfig, /Schemas and /ResourceTypes, relative to the base URL. Confirm that the connector accepts the metadata and recognizes Users and Groups. Start resource reads with /Users?startIndex=1&count=1 and /Groups?startIndex=1&count=1, then verify pagination using the returned totalResults. An unauthenticated 401 does not validate the connector's credential.
| Identity value | SCIM attribute |
|---|---|
| External username |
userName; use the intended Trustmi/SSO email for initial onboarding |
| Primary account email |
emails[].value with primary: true; must be a valid email |
| First / last name |
name.givenName / name.familyName
|
| Lifecycle status |
active, a Boolean |
| Job title | title |
| Department / division |
department / division under the Enterprise User extension |
The enterprise namespace is urn:ietf:params:scim:schemas:extension:enterprise:2.0:User. Title, department and division are optional strings of at most 255 characters. Use the returned id for persistent correlation; externalId is not persisted or returned. Do not map manager, passwords, roles, entitlements or arbitrary profile fields.
3. Configure supported operations
| Resource | Supported methods |
|---|---|
/Users |
GET, POST |
/Users/{id} |
GET, PUT, PATCH, DELETE |
/Groups |
GET, POST |
/Groups/{id} |
GET, PATCH, DELETE |
- User PATCH supports
add/replaceforactive,name.givenName,name.familyName,title, and enterprise department/division. It does not support attribute removal or username/email changes. An enterprise PATCH path isurn:ietf:params:scim:schemas:extension:enterprise:2.0:User:department. - User PUT replaces supported writable attributes. Use it only when a complete replacement is intended; coordinate identity changes with Trustmi Support.
- Group PATCH updates membership and can rename a group. Use it to add/remove members by their Trustmi User IDs. Do not update membership through a User payload's
groupsattribute. Group PUT is unsupported. - Group membership replacement and clearing are supported but can remove OU assignments. Use individual add/remove operations for initial validation. Group names are case-insensitively unique within an organization and limited to 128 characters.
- For ordinary suspension/reactivation, set User
activetofalse/true. User DELETE soft-deletes and deactivates the account and hides it from SCIM discovery. Group DELETE deactivates the OU and hides it from SCIM discovery without deleting its users. Agree deletion behavior before enabling automated deletes. - User lookup supports equality on
userName; group lookup supports equality ondisplayName. Do not generate unsupported compound filters, Bulk, sorting or ETag-based concurrency operations.
4. Verify with an agreed pilot user and OU
These request templates use placeholders. Include the authentication and media-type headers above. Confirm a dedicated pilot identity and OU with your Trustmi administrator before sending write requests.
First look up an existing account with GET /Users?filter=userName%20eq%20%22scim-pilot%40example.com%22. Review any match and retain its returned id. For a new agreed identity, send POST /Users with:
{
"schemas": [
"urn:ietf:params:scim:schemas:core:2.0:User"
],
"userName": "scim-pilot@example.com",
"emails": [
{
"value": "scim-pilot@example.com",
"primary": true
}
],
"name": {
"givenName": "SCIM",
"familyName": "Pilot"
},
"active": true
}
Retain the returned User id. To deactivate the same account, send PATCH /Users/<USER_ID> with:
{
"schemas": [
"urn:ietf:params:scim:api:messages:2.0:PatchOp"
],
"Operations": [
{
"op": "replace",
"path": "active",
"value": false
}
]
}
Use true to reactivate. To check a profile update, replace the operation's path with title and its value with a string, then verify with GET.
Provision users before assigning OU membership. Look up an existing OU with GET /Groups?filter=displayName%20eq%20%22SCIM%20Pilot%22. For a new agreed OU, send POST /Groups with:
{
"schemas": [
"urn:ietf:params:scim:schemas:core:2.0:Group"
],
"displayName": "SCIM Pilot",
"members": [
{
"value": "<USER_ID>"
}
]
}
Retain the returned Group id. To add a provisioned user to an existing OU, send PATCH /Groups/<GROUP_ID> with:
{
"schemas": [
"urn:ietf:params:scim:api:messages:2.0:PatchOp"
],
"Operations": [
{
"op": "add",
"path": "members",
"value": [
{
"value": "<USER_ID>"
}
]
}
]
}
To remove only that member, use op: "remove" with the same path and member list. Verify with GET /Groups/<GROUP_ID>. Confirm unrelated OU assignments remain intact.
Before expanding provisioning, confirm authenticated discovery, full pagination, profile updates, OU add/remove, deactivation/reactivation and account-to-group correlation in your connector. Have a Trustmi administrator verify roles, permissions and effective OU access separately. A successful credential test alone does not establish complete connector compatibility.
Existing Accounts and Access
Match existing accounts deliberately before allowing updates. POST with an existing active account identity returns 409 uniqueness; it is not an unconditional adoption operation. Do not delete an existing account to force creation. Confirm the matched account and its returned id before allowing profile, lifecycle or membership changes.
SCIM updates and membership operations can make affected existing users SCIM-managed. While provisioning is enabled, manage SCIM-controlled profile/lifecycle and OU membership through the identity platform. Roles and explicit permissions remain managed separately in Trustmi. Changing OU membership can change access scope; an empty membership list must not be assumed to prove that all access has been removed.
Troubleshoot
Attributes that cannot be updated through this integration
- Username and primary email changes through PATCH: not supported. Coordinate email or identity changes with Trustmi Support.
- Other profile attributes: middle name, honorifics, display name, nickname, profile URL, phone numbers, addresses, language, locale, time zone, user type, employee number, cost center, organization, manager, entitlements, and roles are not managed by this integration. Do not map them.
- Passwords: cannot be synchronized through SCIM.
- Trustmi roles and permissions: manage them in Trustmi User Management, separately from these user-profile mappings. Group Push manages organizational-unit membership and can change access scope; review effective access before rollout.
| Symptom | What to check |
|---|---|
| SCIM page or token controls unavailable | Correct Trustmi organization, feature availability, and administrator permissions. |
| 401 Unauthorized | Full production token secret, token expiry/revocation, the correct active organization, and enabled SCIM provisioning. Confirm that the Authorization header contains exactly one Bearer prefix. In Okta API Token, enter only the secret. |
| 403 from Trustmi Portal settings | SCIM settings availability and administrator permissions. Disabled provisioning or an inactive organization causes 401 at the public SCIM API. |
| 400 Bad Request | Required username, valid account email, supported attributes, PATCH shape, equality filter and pagination. Title, department and division must be strings of at most 255 characters. Distinct username/email values require an agreed connector mapping, not an assumption that they must always match. |
| 409 Conflict | An existing user identity or duplicate active group name. Review matching; do not delete existing records solely to force creation. |
| 404 Not Found | Base URL, resource ID, and the connected organization. |
| 405 Method Not Allowed | Check the supported methods. Group PUT is unsupported; use Group PATCH for updates. |
| Credentials pass but provisioning fails | Assignments, To App settings, mappings, and the failed provisioning task. |
| Imports do not update the Okta user profile | Expected for this configuration: Okta remains the profile source. Imported values appear in application import data. Contact Support to review another profile-source configuration. |
| Sign On tab or Email username format setting unavailable | Expected for the SCIM-only version: Okta uses user.login and no Email selector is available. For initial onboarding, use the intended Trustmi/SSO email for username and primary email. Agree distinct values with Support. Other application versions may expose Sign On settings. |
| A user is missing from import | Connected organization, soft-deleted status, and user eligibility. Internal Trustmi support accounts may be excluded. Contact Support rather than changing the account. |
Support Contact
Contact support@trustmi.ai for setup questions, unsupported identity changes, or provisioning errors.
Include your organization, identity platform and connector version, timestamp, request method/path, HTTP status, and a sanitized error or provisioning-task reference. For Okta, include a sanitized System Log event or task reference when available. Never include tokens, passwords, Authorization headers, reset links, or unredacted user payloads.
Comments
0 comments
Please sign in to leave a comment.