nano SIEM
SettingsSingle Sign-On

SCIM provisioning

Supported in:Self-hosted

Let Okta or Microsoft Entra ID push user deactivation and group membership to nano over SCIM 2.0, so access changes right away.

SCIM 2.0 lets your identity provider (IdP) push changes to nano as they happen. When you deactivate someone in Okta or Entra ID, or move them between groups, nano applies it within seconds, without waiting for the user to sign in again.

SCIM and sign-in sync

nano already syncs a user's groups at every SSO sign-in. See How sync works. SCIM adds the changes that happen between sign-ins.

Sign-in syncSCIM
When nano learns about a changeAt the user's next SSO sign-in.When the IdP pushes it, usually within seconds.
Deactivating a user in the IdPNothing happens in nano. Open sessions and API keys keep working until the user signs in again.nano disables the account and revokes its sessions, tokens and API keys at once.
Group changesApplied at sign-in.Applied when the IdP pushes the group.
Creating accountsAt the user's first sign-in.When the IdP assigns the user, before they sign in.

Both use the same group mappings, so you configure access once. SCIM is optional: sign-in sync keeps working with or without it.

Before you start

  • A working SSO provider in nano, with its group mappings. See Set up group mappings.
  • A nano user with full administrator authority. Generating or rotating a SCIM token is an SSO trust change, like changing the issuer. See Who can change providers.
  • nano reachable from the internet over HTTPS. Okta and Entra send SCIM requests from their cloud, not from your network. If you use an IP allowlist, add your IdP's egress ranges.

The SCIM tab

Open Settings → Single Sign-On, open the provider, and choose the SCIM tab. It shows:

  • Base URL: the address the IdP sends requests to. Copy it with the copy button.
  • Token: the bearer token the IdP authenticates with.
  • Last sync: when the IdP last called nano, and whether that call succeeded. A failed call shows the error.
  • Provisioned: how many users and groups the IdP has provisioned.

The tab also warns you when the provider is disabled or invitation-only, because both limit what SCIM can do. See How SCIM works.

Base URL

https://<your nano host>/api/scim/v2/<provider-slug>

For a provider with the slug okta on nano.example.com, that is https://nano.example.com/api/scim/v2/okta. Each provider has its own base URL and its own token.

Generate, rotate and revoke the token

ActionWhat it doesWho can do it
Generate tokenIssues a token and turns SCIM on for the provider.Full administrator authority.
RotateIssues a new token. The old one stops working at once, so update the IdP straight away.Full administrator authority.
RevokeDeletes the token. The IdP can no longer provision or deprovision users until you generate a new one.settings:system.

The token is shown once, when you generate or rotate it. Copy it then. Afterwards the tab shows only its prefix and when it was issued. Treat it like a password: anyone holding it can create accounts for this provider, change their groups and deactivate them.

A token only works for its own provider. It can't see or change users that sign in through another provider.

Revoking a token stops provisioning, but it doesn't reset anything. Users and groups that SCIM already provisioned stay linked, and the Provisioned counts stay the same. If you generate a new token later, the IdP picks up where it left off.

Two provider changes do reset SCIM:

  • Changing the issuer deletes the token and all SCIM state for the provider.
  • Deleting the provider deletes its token and SCIM state with it.

Set up Okta

You can use Okta's catalog app SCIM 2.0 Test App (OAuth Bearer Token), or your organization's own SCIM app integration. Okta matches pushed groups to nano by group name, the same names your sign-in groups claim sends.

  1. In nano, open the provider's SCIM tab, click Generate token and copy the token.

  2. In the Okta Admin Console, go to Applications → Applications → Browse App Catalog, and add SCIM 2.0 Test App (OAuth Bearer Token). Or open your own SCIM app integration.

  3. Open the app's Provisioning tab, then Integration, and click Configure API Integration. Check Enable API integration.

  4. Enter the nano base URL in the base URL field (Base URL, or SCIM connector base URL on your own app), and paste the token in the token field (OAuth Bearer Token). On your own app, set Authentication Mode to HTTP Header and the unique identifier field to userName.

  5. Click Test API Credentials, then Save.

  6. Under Provisioning → To App, click Edit and turn on:

    • Create Users
    • Update User Attributes
    • Deactivate Users

    Leave Sync Password off. nano SSO users sign in through Okta and don't use a nano password.

  7. Click Save.

  8. On the Assignments tab, assign the users or groups to provision. Assign the same people who can sign in to the nano OIDC app.

  9. On the Push Groups tab, click Push Groups and add each group you map in nano, for example siem-admins and siem-analysts. Pushed names must match the nano mappings exactly, including case.

Okta pushes assignments, profile changes, deactivations and group membership within a few seconds.

Set up Microsoft Entra ID

In Entra, provisioning runs on an enterprise application, separate from the app registration you use for sign-in. An app registration created for OIDC can't use Entra's SCIM provisioning template, so create a non-gallery enterprise application just for provisioning.

  1. In nano, open the provider's SCIM tab, click Generate token and copy the token.
  2. In the Microsoft Entra admin center, go to Enterprise applications → New application → Create your own application. Name it, for example nano provisioning, choose Integrate any other application you don't find in the gallery (Non-gallery), and click Create.
  3. Open the new app's Provisioning page and start a new configuration. Set Provisioning Mode to Automatic.
  4. Under Admin Credentials, enter the nano base URL as Tenant URL and paste the token as Secret Token. Click Test Connection, then Save.
  5. Under Settings, set Scope to Sync only assigned users and groups.
  6. On the app's Users and groups page, assign the users and the groups you map in nano.
  7. Leave the default group attribute mappings. Entra sends each group's object ID as externalId, and that is what nano matches.
  8. Set Provisioning Status to On and save.

Entra runs provisioning in cycles, about every 40 minutes. To push a change straight away, use Provision on demand on the app's Provisioning page and pick the user or group.

Entra groups match by object ID

nano matches Entra groups by object ID only, not by display name. Map the object ID in nano, the same value your sign-in groups claim sends. See Microsoft Entra ID.

Display names are ignored because any owner of a group can rename it. Matching by name would let a group owner give their group's members nano access by renaming it to a mapped name.

How SCIM works

Deactivating and deleting users

When the IdP deactivates a user (active=false) or deletes them, nano at once:

  • disables the account;
  • revokes every session, access token and refresh token;
  • revokes the user's API keys.

The user is signed out on their next request. Deleting a user also removes them from their SCIM groups and drops every SSO grant from this provider. nano keeps the account record for the audit trail, and the IdP no longer sees it.

A disabled user keeps their SSO group memberships in nano after a deactivation. This is harmless while the account is disabled, because it can't sign in or use a token. If an administrator enables the account in nano again, those memberships come back with it until the next push or sign-in reconciles them.

Reactivating users

SCIM only reactivates accounts that SCIM itself deactivated. If an administrator disabled the account in nano, it stays disabled. Once an administrator enables or disables the account in nano, that decision is nano's, not the IdP's.

Groups and roles

Pushed groups drive the same group mappings as sign-in:

  • A user added to a pushed group gets the nano groups that group is mapped to.
  • A user removed from a pushed group loses those nano groups at once, and nano revokes their sessions. A push that only adds access keeps the user's sessions.
  • Deleting a pushed group removes the grants it gave.
  • Manual grants are never touched. A group an administrator added by hand in nano stays, even if it is the same group a mapping grants.

Okta groups match by name. Entra groups match by object ID only. See Entra groups match by object ID.

A mapping you add later reaches SCIM users at their next push or sign-in, as it does for sign-in users.

Creating and linking accounts

When the IdP assigns a user, nano finds or creates the matching account:

  • Accounts a sign-in already linked to this provider are adopted. nano doesn't create a duplicate.
  • Existing local accounts with the same email are linked only when the provider's verified domains cover the address. Entra also needs the Directory (tenant) ID. Google never vouches for directory email. Linking removes the account's local password, unless it is a break-glass account, and signs out its sessions.
  • New users are created only when the provider has Create accounts for users in mapped groups on. The account has no access until a mapped group arrives.

On an invitation-only provider, SCIM can't create accounts. Invite the user in nano first, and SCIM can then manage them.

A new SCIM account links to the user's IdP identity at their first SSO sign-in. That sign-in still needs an IdP-verified email. See Verified email is required.

An email change pushed for an address outside the provider's verified domains is ignored.

Break-glass accounts

SCIM can't deactivate or delete a break-glass account, one an administrator set up for break-glass local login. The IdP gets a 403 error. Disable the account in nano if you need to.

Disabled provider or locked license

When the provider is disabled, or the nano license is locked, SCIM accepts deprovisioning only: deactivating and deleting users, removing group members and deleting groups. Creating users, reactivating them and adding group members are refused until the provider is enabled or the license is active again. Offboarding keeps working either way.

Rate limits

  • 1,200 requests per minute per provider.
  • 30 failed authentications per minute per client IP address.

Over a limit, nano returns 429 with a Retry-After header.

Removing access

With SCIM, deactivate the user in the IdP. nano disables the account and revokes its access within seconds.

If your IdP doesn't support SCIM, disable the user in nano when offboarding. See Removing access.

Audit events

SCIM calls are recorded in the platform audit log, with the actor scim:<provider-slug>. Search them with:

metadata.log_source=audit api.service.name=oidc api.operation=scim_*
Action (api.operation)When
scim_token_issuedAn administrator generated or rotated a SCIM token. details.rotated says which.
scim_token_revokedAn administrator revoked the token.
scim_request_deniedA request failed authentication or hit a rate limit. details.reason says why.
scim_user_createdThe IdP provisioned a user. details.resolution is created, adopted, linked or revived.
scim_user_updatedThe IdP changed a user's attributes.
scim_user_deactivatedThe IdP deactivated a user. details.api_keys_revoked counts the API keys revoked.
scim_user_reactivatedThe IdP reactivated a user that SCIM had deactivated.
scim_user_deletedThe IdP deleted a user.
scim_group_created, scim_group_updated, scim_group_deletedThe IdP pushed, renamed or deleted a group.
scim_group_membership_changedGroup members were added or removed. details.grants_reconciled lists the users whose grants changed.

The token, user and membership events are written durably.

Troubleshoot

Start with the Last sync row on the provider's SCIM tab, then the scim_* rows in the audit log.

"Invalid or missing SCIM bearer token"

nano returns 401 with this message, and logs scim_request_denied, when the token doesn't match the provider in the URL.

  • Copy the token again from where you saved it, and paste it into the IdP. Check for leading or trailing spaces and line breaks, and that the whole token was pasted.
  • Check the slug at the end of the base URL is this provider's. Each provider's token only works on its own base URL.
  • If the token was rotated or revoked, generate a new one and update the IdP.

The IdP can't reach nano

The IdP calls nano from its cloud. Check nano is reachable over public HTTPS at the base URL, and that an IP allowlist doesn't block the IdP.

"SCIM cannot create new accounts"

The provider is invitation-only. Turn on Create accounts for users in mapped groups, or invite the user in nano first.

"This provider's verified domains do not vouch for the address"

A local account with the same email exists, and nano won't link it without a verified domain. Add the domain to the provider's verified domains, or remove or rename the local account.

"This account is a local break-glass account"

SCIM can't deactivate or delete break-glass accounts. Disable it in nano, or leave it out of the IdP assignment.

"SCIM accepts only deprovisioning"

The provider is disabled, or the license is locked. Enable the provider, or renew the license.

A pushed group grants nothing

  • The group isn't mapped in nano, or the mapping doesn't match exactly. Okta needs the exact group name. Entra needs the group's object ID, not its name.
  • The mapping was added after the push. It applies at the user's next push or sign-in.

Entra reports "already match" or sends the old membership

Entra read a stale replica. Wait 20 to 40 seconds and provision on demand again.

What's next

On this page