Directory sync: Entra ID and Okta

Directory sync connects your company directory to one Velrix organisation. The directory adds people, keeps their names, addresses and roles up to date, and removes them. It uses SCIM 2.0, the standard Microsoft Entra ID and Okta use to provision applications.

When the directory deactivates or deletes someone, Velrix does all of this at once:

• suspends their account, so they can’t sign in with a password or through your identity provider;
• signs them out of every session, on every screen;
• revokes their personal API keys and the apps connected to their account;
• removes them from the organisation, its teams and their roles;
• records it in the organisation’s history and the audit log, with the token that asked and why.

Turning them active again lets them sign in. It does not bring back the keys that were revoked.

Deleting someone in the directory does not erase their account. Erasure is a separate step, because records such as invoices are kept for seven years.

Before you start

• You need to be the organisation’s Owner (directory sync changes who is in the organisation).
• To give people roles from their groups, your operator must have added your company’s sign-in provider (Entra ID or Okta) under Manager › Sign-in providers. Without one, everyone the directory adds joins as a Member.
• People sign in through that provider. An account the directory creates has no password.

Turn it on in Velrix

1. Open Organisations, choose your organisation, and open the Directory sync tab.
2. Choose your Sign-in provider for group mapping, turn Directory sync on, and select Save.
3. Select Make token. Copy the SCIM URL and the Bearer token. The token is shown only once: if you lose it, make a new one.
4. Under Groups and roles, map each directory group to a role:
   • Entra ID: the group’s Object ID.
   • Okta: the group’s name.
   
   A person gets the highest role any of their groups maps to, otherwise Member. The directory never makes anyone an Owner, and never changes an Owner.

The mapping is the same one your sign-in provider uses, so signing in and directory sync always agree.

Connect Microsoft Entra ID

1. In the Microsoft Entra admin center, open Enterprise applications and the application you use to sign in to Velrix. If there is none, choose New application › Create your own application › Integrate any other application you don’t find in the gallery.
2. Open Provisioning and set Provisioning Mode to Automatic.
3. Under Admin Credentials:
   • Tenant URL: the SCIM URL, followed by ?aadOptscim062020. This makes Entra ID follow the SCIM standard more closely. Velrix also accepts Entra’s older requests.
   • Secret Token: the bearer token.
   
   Select Test Connection, then Save.
4. Under Mappings › Provision Microsoft Entra ID Users, keep userName, active, displayName, emails[type eq "work"].value, name.givenName, name.familyName and externalId. Velrix ignores other attributes, such as the department or manager, so you can remove them.
5. Under Mappings › Provision Microsoft Entra ID Groups, keep displayName, externalId (the object ID) and members.
6. Under Settings, set Scope to Sync only assigned users and groups. Assign the people and groups under Users and groups.
7. Set Provisioning Status to On and select Save.

Entra ID provisions every 40 minutes. To try one person at once, use Provision on demand.

Connect Okta

1. In the Okta Admin Console, open the application you use to sign in to Velrix. On General, edit App Settings and set Provisioning to SCIM.
2. Open Provisioning › Integration and fill in:
   • SCIM connector base URL: the SCIM URL.
   • Unique identifier field for users: userName.
   • Supported provisioning actions: Push New Users, Push Profile Updates and Push Groups.
   • Authentication Mode: HTTP Header, with the bearer token as Authorization.
   
   Select Test Connector Configuration, then Save.
3. Under Provisioning › To App, enable Create Users, Update User Attributes and Deactivate Users.
4. Assign people under Assignments, and push groups under Push Groups.

Who the directory may change

• New people: an address nobody uses gets a new account.
• People already in the organisation: someone you invited before turning on directory sync is taken over by the directory when it first names them.
• Anyone else: an address that belongs to an account outside your organisation is refused (409). Invite the person first if they should be managed.

An account belongs to one organisation’s directory at a time. The directory changes the sign-in address only of accounts it created.

Status and errors

The Directory sync tab shows when the directory last synced, how many people it manages, and its most recent errors, such as a refused token or an address that belongs to someone else.

• Revoke token: the directory is refused until you make a new token. Nobody is removed.
• New token: the old token stops working at once.
• Directory sync off: every request is refused and nothing changes.

What is not supported

• Bulk requests, sorting and ETags.
• Filters other than eq, joined with and, on userName, externalId, id, displayName and members.
• Passwords: the directory can’t set one. People sign in through your identity provider.