Outbound provisioning

Outbound provisioning keeps an application’s own user list in step with your directory, over the application’s SCIM 2.0 API. EZGH SSO creates the people assigned to the application there, updates them when they change, and deactivates them when they’re unassigned or suspended. It can push the application’s assigned groups too.

Provisioning works for oidc and saml applications. ezgh applications are EZGH products and aren’t provisioned (409 provisioning_not_supported). You need sso.provisioning.update to change the settings (in SsoFullAccess), and sso.provisioning.get to see them and their status.

Turn on provisioning

You need the application’s SCIM base URL and a bearer token from the application. The catalog has the base URL and mappings for the applications that support SCIM, with the vendor’s steps for getting a token.

ezgh sso applications provisioning set Slack --catalog slack --bearer-token-stdin < slack-token.txt

ezgh sso applications provisioning set Wiki --base-url https://wiki.acme.com/scim/v2 --bearer-token-file token.txt \
  --attribute-mapping 'userName=${user.email}' --attribute-mapping 'displayName=${user.name}' --push-groups

curl -X PUT https://sso.ezghcloud.com/v1/organizations/$ORG_ID/sso/applications/$APP_ID/provisioning \
  -H "Authorization: Bearer $EZGH_API_KEY" -H "Content-Type: application/json" \
  -d '{ "baseUrl": "https://wiki.acme.com/scim/v2", "bearerToken": "…", "pushGroups": true }'

Settings

The answer also shows configured (false until the first PUT), status, and when the settings were created and last changed.

• Changing baseUrl starts over: what was pushed to the old URL is forgotten, everyone is pushed to the new one, and nothing is deprovisioned at the old one.
• Turning it on, or changing anything while it’s on, pushes everyone assigned and everyone pushed before again. Users whose pushed values haven’t changed aren’t sent anything.

Attribute mappings

A mapping is { "target", "source" }. The mappings must include userName, and each target appears once.

target is a SCIM attribute path, up to 320 characters:

• a core attribute or sub-attribute: userName, displayName, title, name.givenName;
• one typed value of a multi-valued attribute: emails[type eq "work"].value;
• an extension’s attribute: urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:department.

id, externalId, active, meta, schemas, groups, members and password can’t be mapped. EZGH SSO sets externalId to the directory user’s ID on users it creates, and active from their status and assignment.

source is up to 512 characters of text with these variables:

A value that comes out empty isn’t sent.

The default mappings:

[
  { "target": "userName", "source": "${user.email}" },
  { "target": "emails[type eq \"work\"].value", "source": "${user.email}" },
  { "target": "name.givenName", "source": "${user.givenName}" },
  { "target": "name.familyName", "source": "${user.familyName}" },
  { "target": "displayName", "source": "${user.name}" }
]

ezgh sso applications provisioning set --default-mappings goes back to them. The catalog’s scim.attributeMappings use the same format.

What’s pushed

A push is queued, in the same transaction as the change, whenever something may change what an application should have:

• assignments added, removed or replaced, directly or for a group;
• a user’s profile changed, or the user suspended, reactivated or deleted, by you or by inbound SCIM;
• group membership changed: by you, by inbound SCIM, by an identity provider’s group mappings at sign-in, or by deleting an identity provider;
• a group renamed or deleted.

Each push reads the directory as it is when it runs, so the order of changes doesn’t matter.

How a user is pushed: a user EZGH SSO already knows at the application is updated with PATCH. Otherwise EZGH SSO looks for them by externalId (a user it created), then by userName, and only then creates them with POST. A user found by userName is adopted: EZGH SSO updates them, but didn’t create them, so reconcile doesn’t repair them. Updates replace the mapped attributes (a mapped multi-valued attribute is replaced whole) and active; attributes you don’t map are never touched. A change that doesn’t alter anything pushed sends nothing.

Groups

With pushGroups, the groups assigned to the application are pushed with displayName (the group’s name), externalId (the group’s ID) and their members who are active at the application. A group is looked up by externalId, then displayName, before it’s created. Members are added and removed with PATCH, and only users EZGH SSO pushed are ever removed.

A group that’s no longer pushed (unassigned, deleted, or pushGroups turned off) is deleted at the application if EZGH SSO created it, and left alone otherwise.

Deprovisioning

• Unassigning or suspending a user always sends active: false, which most applications treat as deactivation. The user stays at the application.
• Deleting a directory user sends active: false, or with hardDelete, DELETE.
• Deleting the application, or the directory, stops provisioning without deprovisioning anyone at the application. To deactivate everyone first, unassign them and wait for the pushes.

Retries and status

A failure is kept as the user’s (or group’s) lastError: the status, and the application’s SCIM detail and scimType, up to 300 characters. A user whose push stopped stays flagged until a later change, a reconcile or a settings change pushes them successfully. Requests time out after 30 seconds, and answers over 1 MiB are refused.

GetProvisioning (ezgh sso applications provisioning get) shows status:

status also counts the queued pushes, users (active, inactive, errors) and pushed groups, and shows the last success, the last error, and the last and next reconcile. To see each user or group:

ezgh sso applications provisioning users Wiki --status error
ezgh sso applications provisioning groups Wiki

ListProvisionedUsers (status: active, inactive, none or error) and ListProvisionedGroups (status: error) list each record newest first: the application’s ID for it, whether EZGH SSO created it there (createdByEzgh), whether a push is pending, and the last push and error.

Reconcile

A reconcile compares the application’s users with the directory and repairs drift. It runs every week, counted from when provisioning was turned on, and within seconds when you ask:

ezgh sso applications provisioning reconcile Wiki

A reconcile lists the application’s users (GET /Users, at most 10,000), then pushes again:

• each user EZGH SSO created there that’s missing, has a mapped value or active that differs, or should be gone;
• each flagged user;
• each assigned user who isn’t there yet;
• each pushed group.

Users EZGH SSO adopted, or never touched, aren’t repaired. If listing fails with a 429, the reconcile pauses and retries; another failure retries in 15 minutes, except a 4xx, after which every user EZGH SSO created is pushed again instead (shown in lastReconcileError).

Activity in Trails

Each push that changes something at the application is recorded in Trails as a service event by sso.ezghcloud.com, naming the application and the user or group: ProvisionUser (create, update or adopt), DeprovisionUser (deactivate or delete) and ProvisionGroup (create, update with the members added and removed, or delete). A push that stops is recorded once, with errorCode provisioning_failed. Retries and pauses aren’t recorded, and neither the bearer token nor attribute values ever are.