Enterprise Identity & Access

This guide explains how to connect the platform to enterprise identity systems and govern the access they grant. It is written for tenant administrators and platform administrators who manage provisioning, single sign-on, and access reviews.

1. How Provisioning Works

The platform supports three ways to bring users and their access in from enterprise systems, plus a direct API for custom integrations. All paths converge on the same access model: groups from the source system are translated into platform roles through group-to-role mappings, and every role grant is checked against Segregation-of-Duties (SoD) rules before it is applied.

Provisioning Path	What It Does	Typical Use
SCIM 2.0	Your identity provider pushes user and group changes to the platform in real time.	Azure AD, Okta, and other SCIM-capable IdPs.
SSO just-in-time (JIT)	A user account is created or updated automatically on first successful sign-in.	SAML or OIDC logins where you do not run SCIM.
LDAP directory sync	The platform pulls users from an on-premises directory on demand.	Active Directory or other LDAP directories.
IAM provisioning API	A custom integration looks up, upserts, or deprovisions users directly.	Scripts and middleware where SCIM is not available.

Key principles:

• Group membership in the source system drives platform roles through group-to-role mappings.
• No role is granted if it would create a Segregation-of-Duties conflict; the assignment is blocked instead.
• Machine integrations (SCIM, LDAP sync, the provisioning API, and access-review export) authenticate with IAM service-account tokens, not user passwords.

2. IAM Service Accounts

IAM service accounts are non-human identities used by integrations. Create and manage them under Settings → IAM service accounts. Managing service accounts requires the settings.manage permission (or system administrator).

When you create a service account, a token is generated in the form grc_iam_.... The full token is shown only once at creation, so copy it immediately into your secret store; the platform keeps only a hashed copy and cannot display it again.

Each token can be limited to the scopes the integration actually needs:

Scope	Grants
users.read	Read user records.
users.write	Create and update users.
users.deprovision	Deactivate and offboard users.
scim.users	SCIM user provisioning.
scim.groups	SCIM group (role) provisioning.
access_reviews.read	Run the access-review export.
directory.sync	Run LDAP directory synchronization.

Service-account controls:

• Set an optional expiry date so unused tokens lapse automatically.
• The platform records the last-used time and IP address for each token.
• Revoke a token at any time to immediately cut off the integration.

Grant the narrowest set of scopes required, rotate tokens on a schedule, and revoke any token that may have been exposed.

3. SCIM 2.0 Provisioning

SCIM 2.0 is the primary path for automated provisioning. Identity providers such as Azure AD and Okta use it to keep users and group memberships in sync with the platform automatically.

Connection

Setting	Value
Base path	/scim/v2
Authentication	IAM service-account token in the X-IAM-Token header, or Authorization: Bearer <token>.
Required scopes	scim.users for user operations, scim.groups for group operations.
Discovery	ServiceProviderConfig, Schemas, and ResourceTypes endpoints describe supported capabilities.

Supported operations

Resource	Operations
Users	List, get by ID, create, replace (PUT), update (PATCH), delete.
Groups	List, create, replace (PUT), delete.

PATCH on a user supports updating active status, display name and formatted name, email addresses, and group membership (add, remove, and replace), including filtered membership changes such as groups[value eq "..."].

Behavior and limits

• Filtering supports the eq operator only.
• A maximum of 200 results is returned per page.
• Bulk operations, sorting, ETag concurrency, and password change are not supported.
• A SCIM group maps to a platform (tenant) role. Assigning roles that would violate an SoD rule is rejected with HTTP 409.
• Deleting a user is a soft deprovision: the account is deactivated, placed under a long lockout, has its tokens cleared, and has its role grants removed. The record is preserved for audit and reporting.

Connecting Azure AD or Okta

1. Create an IAM service account with the scim.users and scim.groups scopes and copy the token.
2. In your identity provider, configure SCIM provisioning using the platform SCIM base URL and the token (as a bearer token).
3. Map the IdP groups you want to provision to platform roles, then enable provisioning.

4. SSO Configuration (SAML & OIDC)

Single sign-on is configured under Settings → SSO and requires the settings.manage permission. The platform supports SAML, OAuth/OIDC, Azure AD, Okta, and Google providers. The provider list is published on the login page, so users can choose their organization's sign-in method.

SAML security

SAML responses are validated against the following controls:

• X.509 certificate signature validation.
• Replay protection to reject reused responses.
• A validity window (NotBefore / NotOnOrAfter) with a small allowance for clock skew.
• Issuer and audience checks.
• Optional hardening flags to require signed assertions or a signed response, an expected issuer, and an expected audience.

OIDC security

OIDC sign-ins validate the id_token expiry, issuer, and audience.

Just-in-time provisioning

When JIT is enabled, a user who signs in successfully is provisioned automatically using a configured default role and JSON attribute mappings. Group-to-role mapping is then applied, and every resulting role grant passes through Segregation-of-Duties enforcement, so an SSO login can never create a conflicting role combination.

5. LDAP Directory Integration

Note: LDAP integration is configured through the API only; there is no settings screen for it yet. Manage it with the settings.manage permission or as a system administrator.

Each tenant can hold its own LDAP configuration:

Setting	Purpose
Host / port	Directory server address.
Security	SSL (LDAPS) or StartTLS.
Bind DN / bind password	Service account used to query the directory. The bind password is write-only and is never returned.
User search base	Where in the directory tree to search for users.
User search filter	The search filter; it must contain the {0} placeholder for the username.
Attribute mappings	Map directory attributes to platform user fields.
Auto-provision	Whether matched directory users are created automatically.
Sync disabled users	Whether accounts disabled in the directory are reflected in the platform.
Default role	Role assigned to newly provisioned users.

Operations:

• Test connection verifies the host, security mode, and bind credentials.
• Sync users pulls users from the directory; users no longer present in the directory can be disabled by the sync.

6. Segregation of Duties (SoD)

Note: SoD rules are configured through the API only; there is no settings screen for them yet.

A Segregation-of-Duties rule pairs two roles and assigns a severity of Medium, High, or Critical. Whenever a user would end up holding both roles of an active rule, the assignment is blocked with HTTP 409 and an audit entry is recorded.

SoD enforcement is not advisory. It applies consistently across every provisioning path:

• SCIM group assignments.
• The IAM provisioning API.
• SSO group-to-role mapping.

This guarantees that no integration can grant a toxic combination of roles, regardless of how the user was provisioned.

7. Access Reviews and Governance

The platform provides an access-review export to support periodic recertification. The export is a CSV listing every user together with:

• their assigned roles,
• their effective permissions,
• their lock, active, and deleted state,
• a computed Privileged flag that highlights elevated access.

Use the export to review who holds what access, confirm each grant is still appropriate, and document recertification decisions. The export is available to interactive administrators and to service accounts holding the access_reviews.read scope, so it can be pulled on a schedule by a governance integration.

8. IAM Provisioning REST API

For custom integrations where SCIM is not available — scripts, middleware, or an HR system driving onboarding — the platform exposes a small provisioning API under api/iam/provisioning. Each call authenticates with an IAM service-account token and requires the matching scope.

Operation	Endpoint	Scope	Purpose
Look up a user	GET api/iam/provisioning/users/by-email	users.read	Find an existing user by email address.
Create or update a user	PUT api/iam/provisioning/users	users.write	Upsert a user and set their roles by role code.
Deprovision a user	POST api/iam/provisioning/users/deprovision	users.deprovision	Disable a user and revoke their access.

Notes:

• Roles are assigned by role code, not by internal identifier, so the same payload works across tenants that share a role catalogue.
• Every role grant is Segregation-of-Duties enforced in the same way as SCIM and SSO — a request that would create a conflicting role combination is rejected.
• Deprovisioning is thorough: the user is deactivated and locked out, their refresh, password-reset, and invitation tokens are cleared, and their role grants are removed. This matches the soft-deprovision behavior of a SCIM DELETE.
• An optional reason can be supplied on deprovision and is written to the audit log.

SCIM 2.0 remains the recommended path for mainstream identity providers; use this API only when a direct integration is required.

9. Group-to-Role Mappings

Every provisioning path — SCIM, SSO just-in-time, LDAP sync, and the provisioning API — translates a group from the source system into a platform role through a shared group-to-role mapping registry. Maintaining the mappings in one place keeps role assignment consistent no matter how a user arrives.

A mapping records the external group (with its source — SCIM, SSO, OIDC, or a named provider) and the tenant role it grants. The registry is managed via api/iam/enterprise/group-role-mappings (list and upsert); like SoD rules and LDAP configuration, it is currently API-only and has no dedicated screen yet. When a source group is added to a user, the mapped role is granted — subject to the same Segregation-of-Duties checks described above.