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

# SCIM Inbound Provisioning

> Overview of inbound SCIM 2.0 user and role provisioning in Genesis.

Genesis operates as a SCIM 2.0 service provider. Your Identity Provider (IdP)
pushes users and groups to Genesis at `https://<genesis-host>/scim/v2`, and
Genesis automatically creates, updates, deactivates, and re-roles the matching
users.

This page is the entry point. Use the linked pages for IdP-specific setup,
admin API usage, validation, monitoring, and security.

<CardGroup cols={2}>
  <Card title="Admin API" href="/docs/Setup/SCIM-Admin-API">
    Generate and rotate SCIM bearer tokens, configure group-to-role mappings.
  </Card>

  <Card title="IdP Setup Guides" href="/docs/Setup/SCIM-IdP-Setup-Guides">
    Step-by-step instructions for Okta, Azure Entra ID, OneLogin, and
    AWS-sourced provisioning.
  </Card>

  <Card title="Okta Setup Guide" href="/docs/Setup/SCIM-Okta-Setup-Guide">
    Screenshot-backed Okta setup and validation walkthrough.
  </Card>

  <Card title="Pilot Runbook" href="/docs/Setup/SCIM-Pilot-Runbook">
    Preflight, validation, conformance harness, and rollback steps.
  </Card>

  <Card title="API Reference" href="/docs/Setup/SCIM-API-Reference">
    Endpoint reference with request and response examples.
  </Card>

  <Card title="Monitoring" href="/docs/Setup/SCIM-Monitoring">
    Signals to track, suggested alerts, and audit queries.
  </Card>

  <Card title="Security" href="/docs/Setup/SCIM-Security">
    Security controls, risks, and production recommendations.
  </Card>
</CardGroup>

## Capabilities

| Area | Supported |
| - | - |
| `/scim/v2/Users` | Create, read, list, filter (`userName eq`), replace, patch, soft deactivate |
| `/scim/v2/Groups` | Create, read, list, filter, replace, patch (add/remove members), delete (membership cleanup only) |
| Metadata endpoints | `/ServiceProviderConfig`, `/ResourceTypes`, `/Schemas` |
| Authentication | Per-tenant bearer tokens (rotatable, persisted as hashes) |
| Group → role mapping | Per-tenant configurable, 1:1 mapping |
| Audit | Every operation persisted in `SCIM_AUDIT_LOG` with before/after snapshots |
| Deprovisioning | Soft `active=false`. Genesis never hard-deletes from SCIM operations. |
| SCIM-managed user lock | Manual role edits blocked in UI, API, and admin tooling. |
| Login admission gate | Optional: restrict OIDC sign-in to active SCIM-provisioned users. |
| Rate limiting | Per-token, in-process. Use ingress/WAF/API gateway for strict global limits. |
| Validation harness | Repeatable conformance check that exercises the live endpoint. |

## Out of scope for the current release

* SCIM Bulk operations.
* Custom schema extensions beyond the SCIM Enterprise User extension fields
  documented in the [API Reference](/docs/Setup/SCIM-API-Reference#user-payload-example).
* Outbound SCIM (Genesis pushing to an IdP).
* IdP pull sync (Genesis polling an IdP).
* ETag / `If-Match` optimistic concurrency.

## How it fits together

```text theme={null}
Customer IdP ──HTTPS──>  https://<genesis-host>/scim/v2 ──> Genesis
                          (Bearer token auth)                ├─ Users table
                                                             ├─ Roles + memberships
                                                             └─ SCIM_AUDIT_LOG
```

1. An admin generates a SCIM bearer token in Genesis.
2. An admin configures the group-to-role mapping in Genesis.
3. The IdP is configured with the SCIM base URL plus the bearer token.
4. The IdP pushes user and group changes whenever they happen on its side.
5. Genesis applies the changes, persists audit rows, and reflects role changes.

## Configuration

SCIM is configured through environment variables on the Genesis deployment plus
admin REST calls into the running app.

### Environment variables

| Variable | Purpose | Default |
| - | - | - |
| `GENESIS_SCIM_BEARER_TOKEN` | Initial bearer token used by the IdP. Treat like a password. Rotate before production rollout. | unset |
| `GENESIS_SCIM_GROUP_ROLE_MAPPING` | JSON map from IdP group identifier to Genesis role name. Map only groups you intend to push from the IdP. | unset |
| `GENESIS_SCIM_REQUIRE_PROVISIONED_USERS` | When `true`, sign-in is restricted to active SCIM-provisioned users. Enable only after pilot users are verified. Ignored in a Databricks App, where SCIM is refused. | `false` |
| `GENESIS_SCIM_RATE_LIMIT_PER_MINUTE` | Per-token rate limit. For multi-replica deployments use ingress-level limits for strict global control. | `600` |
| `GENESIS_SCIM_TENANT_ID` | Tenant identifier persisted on SCIM tokens, mappings, and audit rows. | `default` |

<Warning>
  Treat the SCIM bearer token like a password. Store it in your IdP's secret
  field and your deployment secret manager. Do not put it in screenshots,
  shared tickets, or shell history.
</Warning>

### Helm values example (Kubernetes deployments)

```yaml theme={null}
config:
  extraEnv:
    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"
```

For deployment-specific guidance on AWS EKS, see
[Deploying Genesis - Kubernetes on AWS](/docs/deployments/AWS/Genesis-On-AWS#inbound-scim-for-awseks-deployments).

## Quick start

<Steps>
  <Step title="Generate a SCIM bearer token">
    Call the [admin API](/docs/Setup/SCIM-Admin-API) as a Genesis admin:

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

    Save the returned plaintext token immediately. Genesis only returns it once.
  </Step>

  <Step title="Configure the group-to-role mapping">
    ```bash theme={null}
    PUT /api/config/scim/group-role-mapping
    Content-Type: application/json

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

    Mapping keys can be the IdP group **display name** or the IdP **externalId**.
    Use whatever your IdP sends as the group identifier on the SCIM `Group`
    resource. The example names above are illustrative.
  </Step>

  <Step title="Configure the IdP">
    Follow the step-by-step instructions in
    [SCIM IdP Setup Guides](/docs/Setup/SCIM-IdP-Setup-Guides). Common values
    for any IdP:

    * **SCIM base URL:** `https://<genesis-host>/scim/v2`
    * **Auth:** Bearer token (from step 1)
    * **userName:** primary email address
    * **Groups:** push only the groups present in the Genesis mapping
    * **Deprovisioning:** send `active=false`
  </Step>

  <Step title="Pilot validation">
    Run the [SCIM Pilot Runbook](/docs/Setup/SCIM-Pilot-Runbook) end-to-end on a
    pilot user before enabling SCIM-only login admission for the deployment.
  </Step>

  <Step title="Enable SCIM-only login (optional)">
    After the pilot succeeds, set
    `GENESIS_SCIM_REQUIRE_PROVISIONED_USERS=true` to restrict sign-in to
    active, SCIM-provisioned users.
  </Step>
</Steps>

## SCIM-managed users in the dashboard

Users provisioned through SCIM are labelled `Managed by SCIM` in the
[Users and Roles](/docs/Setup/Users-And-Roles) page. Manual role add and revoke
controls are intentionally hidden for these users. Update the user's IdP group
membership and the SCIM group-to-role mapping instead of editing role badges in
Genesis directly.

## Compliance summary

* Every SCIM operation (user create/update/deactivate, group sync, group
  delete, token rotation, mapping update) writes a row to `SCIM_AUDIT_LOG`
  with tenant, operation, resource type, resource ID, externalId, before JSON,
  after JSON, and timestamp.
* Persisted bearer tokens are stored as hashes; plaintext tokens are returned
  only once at rotation time.
* Deprovisioning is always soft (`active=false`); Genesis does not hard-delete
  users in response to SCIM operations.
* For regulated customers, see [SCIM Monitoring](/docs/Setup/SCIM-Monitoring)
  for SIEM export guidance.

## Limitations and known caveats

* **No outbound SCIM.** Genesis does not push users or groups to an IdP.
* **No pull sync.** Genesis does not poll an IdP's SCIM endpoint.
* **No SCIM Bulk operations.**
* **No custom schema extensions** beyond the SCIM Enterprise User extension
  fields documented in the [API Reference](/docs/Setup/SCIM-API-Reference#user-payload-example).
* **No ETag / `If-Match` concurrency.** Genesis returns weak version metadata
  but does not enforce optimistic concurrency.
* **No dedicated admin UI** for token rotation or mapping management in this
  release. Use the [admin REST API](/docs/Setup/SCIM-Admin-API).
* **Per-token rate limiting is in-process.** For multi-replica deployments,
  enforce global limits at ingress, WAF, API gateway, or a shared limiter.
* **AWS IAM Identity Center is not a native outbound SCIM source** for
  arbitrary applications. See
  [SCIM IdP Setup Guides — AWS-sourced provisioning](/docs/Setup/SCIM-IdP-Setup-Guides#aws-sourced-provisioning)
  for the supported pattern.