SCIM for your users

SCIM for your users

When an endpoint asks people to sign in, ngris keeps its users. With SCIM, your company's identity provider (Okta, Microsoft Entra ID, OneLogin or any SCIM 2.0 provider) keeps that list for you: it adds the people you assign to the app, changes them when they change, and deactivates them when they leave, who are then signed out at once. Its groups can give roles.

SCIM is about the users of your endpoint, the people who sign in to your site. It doesn't change who signs in to ngris.

  1. Open the endpoint's Sign-in & access tab, section Sign-ups, card SCIM.
  2. Click Make a token. SCIM turns on. Copy the token it shows (scim_…): it isn't shown again.
  3. Copy the Base URL: https://api.ngris.com/scim/v2/endpoints/<endpoint uuid>.
  4. Paste both in your identity provider (Okta, Microsoft Entra ID, others) and assign the people and groups.
  5. Under Groups give roles, give a role to each group your provider sends (below).

The same from the API: POST /v1/endpoints/{uuid}/scim/token, then PUT /v1/endpoints/{uuid}/scim for the rules (API docs).

SCIM is an endpoint feature of every plan; an admin can set it per plan. Without it, your provider's calls are refused, and the users SCIM added stay.

Okta

In the Okta app your users sign in with (the SAML app of this endpoint, for example):

  1. General → App Settings → Edit: set Provisioning to SCIM and save.
  2. Provisioning → Integration → Edit: SCIM connector base URL is the base URL; Unique identifier field for users is userName; under Supported provisioning actions, tick Push New Users, Push Profile Updates and Push Groups (the two imports work too); Authentication Mode is HTTP Header, with the token as the bearer token. Click Test Connector Configuration, then save.
  3. Provisioning → To App → Edit: turn on Create Users, Update User Attributes and Deactivate Users.
  4. Assign people or groups in Assignments, and pick the groups to send in Push Groups.

Microsoft Entra ID

In Enterprise applications, open the app your users sign in with:

  1. Provisioning: set Provisioning Mode to Automatic.
  2. Admin Credentials: Tenant URL is the base URL, Secret Token the token. Click Test Connection, then save.
  3. Keep the default Mappings: the user principal name becomes the userName, the mail the email.
  4. Under Settings, keep Sync only assigned users and groups, set Provisioning Status to On and save.

Entra syncs on its own schedule: a first full sync, then about every 40 minutes. A change can take that long to arrive.

Other identity providers

Any SCIM 2.0 provider works with three settings: the base URL, the token sent as Authorization: Bearer scim_…, and userName as the users' unique field. OneLogin, for example, has a SCIM 2.0 app for this. What ngris answers is below.

What SCIM does to your users

Your providerOn ngris
Adds a userA new active user with the email, name and username it sends, the role New users get, and the roles of their groups. Your plan's user limit applies: over it, the user isn't added and Last calls says why.
Adds someone who's already a user hereWith the same email, a user you added or invited, or one who joined through SAML, is taken over: SCIM keeps them up to date from now on. They keep their roles and how they sign in. Not someone who signed themselves up, a user the ngris agent made, an invite not accepted yet, a revoked user, or a user SCIM already keeps under another userName: your provider gets a refusal (409), shown in Last calls.
Changes a userTheir email, name and username change here too.
Deactivates a user (unassigned, suspended, left)They're disabled and signed out everywhere at once. Turned back on, they're active again; a user you revoked stays revoked.
Deletes a userThey're deleted here.
  • You can still edit, disable or remove these users by hand. Your provider's next change of a user wins for what it sends.
  • Each change sends its user event, as a change you make does.
  • Your provider's other fields (title, department, phone numbers, manager) are accepted and not kept.

Groups give roles

A group holds no rights on its own. Each rule on the SCIM card gives one of the endpoint's roles to the members of one group: Acme-Editors → editor. Up to 200 rules.

  • Type the group's name exactly as your provider sends it, letter case included: acme-editors isn't Acme-Editors. A group can give several roles, and several groups the same role.
  • A user gets a rule's role when they join its group, and loses it when they leave every group that gives it. Saving the rules applies them to every SCIM user at once.
  • Roles you give by hand stay, whatever the groups say.
  • The same role given by SAML group rules and by SCIM is held once. Give each role through one of the two.

How SCIM users sign in

SCIM adds users; it isn't a way to sign in. A SCIM user signs in with the endpoint's sign-in methods that find them:

  • SAML: their first SAML sign-in connects them, by email, when the identity provider's Email domains it may use include their email's domain (how a user is connected). Pick who can join in Sign-ups: with sign-ups switched off, nobody is connected.
  • An emailed code or a provider with the same verified email, when the endpoint has them.

The token, on and off

  • The card names the token by its last four characters and when it was made. Lost it? Click New token: the old one stops at once, and your provider's calls fail until you paste the new one there.
  • Turn off removes the token: your provider's calls are refused. The users and groups SCIM added stay, with their roles. A new token turns SCIM on again and goes on where it stopped.
  • Your account's activity log has every change your provider makes, shown as SCIM (your endpoint's address), beside turning SCIM on or off, a new token and saving the rules.
  • Last calls lists your provider's latest 20 changes from the last 30 days: what, who, when, and the result, with the reason of a refusal.

What ngris answers

SCIM 2.0 (RFC 7643 and 7644) at https://api.ngris.com/scim/v2/endpoints/<endpoint uuid>:

PathMethods
/Users, /Users/{id}GET, POST, PUT, PATCH, DELETE
/Groups, /Groups/{id}GET, POST, PUT, PATCH, DELETE
/ServiceProviderConfig, /ResourceTypes, /SchemasGET
  • User fields kept: userName (one per user of the endpoint, letter case ignored), externalId, name.givenName, name.familyName, displayName, emails (the primary one, else the first, is the user's email), photos (the primary one, else the first of type photo, else the first: an https address, the user's picture; not sent back) and active. A user's id is their id on ngris.
  • Group fields kept: displayName (one per group of the endpoint), externalId and members (users of this endpoint).
  • Filters: eq on userName, externalId and emails.value for users, on displayName and externalId for groups. Pages of up to 200 (startIndex, count); excludedAttributes=members lists groups without their members.
  • PATCH: add, replace and remove, with or without a path, as Okta and Microsoft Entra ID send them.
  • ngris answers without bulk requests, sorting, ETags, password changes and filters joined with and or or, as its /ServiceProviderConfig says; Okta and Entra don't use them. A body is up to 1 MiB.
AnswerWhen
401The token is missing or wrong, SCIM is off, or the base URL isn't this token's endpoint. Paste a new token.
403The plan doesn't include SCIM, the account is suspended, the endpoint is paused over its plan's limits (changes only), or the plan's user limit is reached (a new user).
409Another user or group has this userName, externalId, email or displayName ("scimType": "uniqueness").
429Too many calls in a short time. The answer says when to try again (Retry-After); Okta and Microsoft Entra ID try again on their own.
Was this helpful?