Skip to content

User Provisioning with SCIM

Info

New in Atfinity 18.

Atfinity can receive its users from Microsoft Entra ID over SCIM 2.0, so a user assigned to the Atfinity enterprise application in Entra ID exists in Atfinity before their first login. Roles and user groups can come from Entra ID as well, as described in Roles and user groups. Provisioned users have no password, so they need Single Sign On to log in.

Setting it up

  1. Under Administration -> Auth -> External directory, switch on Enable SCIM user provisioning on the SCIM tab and generate a token. A new token can only be generated after revoking the old one, which stops provisioning until Entra ID has the new token.
  2. In the provisioning settings of the enterprise application, choose automatic provisioning and copy the SCIM base URL into Tenant URL and the token into Secret Token.
  3. In the attribute mappings, turn off provisioning of groups, which Atfinity refuses unless you load user groups from Entra ID groups.
  4. Map userName from the Entra ID attribute that the SAML application sends as the email address claim, since Single Sign On finds the user by that address. By default Entra ID maps userName from the user principal name but sends the mail attribute as the email address, and the two differ for some users.
  5. Assign users or groups to the application and start provisioning.

Atfinity stores userName as the email address, along with active, externalId, name.givenName and name.familyName, and ignores every other attribute. The token decides which tenant the users are created in, so one enterprise application provisions one tenant.

Test SCIM connection calls the SCIM base URL from the Atfinity server itself, so a server that cannot reach its own public address fails the test even when Entra ID gets through.

Provisioned users

A new user is active, has access level User, only the roles and user groups that come from Entra ID, and receives no welcome email. Without a role, Single Sign On refuses them, with the message a user without permissions sees, until you give them a role or make them an administrator. With Load roles and groups on login switched on in the SAML tab instead, every login sets their roles, groups and admin rights from the SAML groups, replacing the ones you assigned.

Entra ID owns the email address, the name and the active status, which are read-only, and their password and two-factor key cannot be reset in Atfinity. A valid until date does not apply to them, so neither their user page nor the users overview shows one. An active provisioned user cannot be deleted in Atfinity, and a user import neither deletes provisioned users nor changes those fields or their password.

A user who already exists in the tenant with the same email address, created by hand or copied from LDAP, is taken over the first time Entra ID updates them. They keep their roles, groups and history, and their Atfinity password stops working. Email addresses are unique across the installation, so an address that belongs to a user of another tenant is refused.

An active provisioned user keeps the externalId they were provisioned with, and an update that changes it is refused. This stops Entra ID from turning a user into somebody else when it still remembers user ids from before an Atfinity database was restored or copied. Once Entra ID has deactivated them, a user created again in Entra ID with the same userName takes them over.

Roles and user groups

Roles can come from the app roles of the enterprise application, as described in Roles from Entra ID App Roles, and user groups from the groups assigned to it, as described in User Groups from Entra ID Groups. Both build on the setup above, and neither can be on while Load roles and groups on login is on in the SAML or OpenID Connect tab.

Deactivating and deleting

Disabling, deleting, unassigning or scoping out a user in Entra ID deactivates them at the next provisioning cycle, and assigning them again reactivates them with the roles and groups they had. A deactivated user loses access with their next request, including their open browser session and the tokens of their AI clients. The same happens when you deactivate or lock any user yourself, and Entra ID never unlocks a user you locked.

A user deleted permanently in Entra ID is deleted in Atfinity, the same way as when you delete a user yourself. Entra ID sends no deletion for a user it stopped managing, which it does when they are unassigned or scoped out before being deleted, so you delete such a user yourself once they are deactivated. If Entra ID provisions them again later, they are created anew, as for someone assigned for the first time.

Switching provisioning off

Switching provisioning off releases every provisioned user, and Entra ID's requests are refused from then on. Released users become ordinary users you can edit, and a valid until date they had applies again. A configuration import with Administration settings from an environment where provisioning is off switches it off here the same way, without giving the users a password, and releases the roles and user groups loaded from Entra ID too. After switching provisioning on again, Entra ID takes a released user back over the first time it updates them.

Server requirements

The SCIM base URL is built from PUBLIC_BASE_URL, or BASE_URL where that is not set, and the Helm chart sets it from the host. Without either, the SCIM tab shows no URL.

Entra ID calls the URL from the internet, so a firewall in front of Atfinity has to let in the Entra ID provisioning service, whose addresses Microsoft publishes as the AzureActiveDirectory service tag. It only accepts a certificate issued under one of the public certificate authorities Microsoft lists, so a server with a self-signed or internal certificate cannot be provisioned this way. For a server the internet cannot reach, the Microsoft Entra provisioning agent installed in your network forwards the requests over outbound connections only.

While throttling is enabled, each tenant can make 6000 SCIM requests per minute. Change it with api.scimThrottleRate in the Helm values, or SCIM_THROTTLE_RATE without the chart.