Workflows

Provision people from Okta or Entra ID

On the Enterprise plan, your identity provider can add people to Clock Clerk, keep their names and titles up to date, and take their access away the day they leave. You create a token in Clock Clerk, enter it with Clock Clerk's SCIM address in Okta or Microsoft Entra ID, and choose who is assigned. From then on, the provider does the adding and removing that an administrator otherwise does by hand.

Three ways people arrive

Found in your Microsoft directory. In an organization that signs in with Microsoft, an administrator searches the directory with New person on People, or the person is added the first time they sign in.
Sent by your identity provider. Okta or Microsoft Entra ID sends each person it is told to over SCIM, the standard for provisioning, using a token from the Provisioning tab. This is the way that also removes people: when they leave, the provider says so, and their access ends.
Added by hand. An administrator enters a name and an email address with New person on People. In an organization that signs in with a password or with Okta, and has no provider sending people, this is the only way in.

The three can be mixed, and nobody is added twice. When the provider sends somebody who is already in Clock Clerk at that address, whether added by hand or found in the directory, it takes over that person: their role, grants, projects and history stay as they are. Each person is still matched by their address the first time they sign in, however they were added.

Before you start

You need to be an Admin, and your organization needs to be on the Enterprise plan.
On the Provisioning tab, copy the SCIM address, then create a token with New token, named for the provider, and copy it. It is shown only once.
Decide who should be in Clock Clerk. The provider sends only the people, or the members of the groups, you assign to the app.

People the provider adds arrive as Users who start today, with no grants and on no project's team, just like somebody added by hand. Give them their role and projects on People afterwards. How they sign in does not change: in an organization that signs in with a password, each new person is emailed a link to choose their password, from the administrator who created the token. With Microsoft or Okta, nothing is sent, and they sign in with their work account.

Provisioning from Okta

Use the Okta app integration your people already sign in to Clock Clerk with, so that one assignment gives them both their sign-in and their place in Clock Clerk. In the Okta Admin Console:

Open Applications, then the Clock Clerk app. On its General tab, edit App Settings, choose SCIM under Provisioning, and save. A Provisioning tab appears.
On the Provisioning tab, under Integration, choose Edit and enter:
- SCIM connector base URL: the SCIM address from Clock Clerk.
- Unique identifier field for users: userName.
- Supported provisioning actions: Push New Users and Push Profile Updates. Leave Push Groups off: Clock Clerk does not take groups.
- Authentication Mode: HTTP Header, with the token as the Authorization bearer token.
Choose Test Connector Configuration, then save.
Under To App, choose Edit and turn on Create Users, Update User Attributes and Deactivate Users. Save.
On the Sign On tab, set the Application username format to Email. Clock Clerk matches people by their email address, so it refuses anybody whose Okta username for the app is not their email (see below).
On the Assignments tab, assign the people or groups who should be in Clock Clerk. Each is sent as they are assigned. Okta flags anyone assigned before provisioning was on, and they can be provisioned from the same tab.

Once Okta starts sending, the token's Last used time on the Provisioning tab moves, and the people appear on People within moments.

Provisioning from Microsoft Entra ID

Entra ID provisions from an enterprise application of its own, separate from the one your people sign in through. In the Microsoft Entra admin center:

Open Enterprise applications, choose New application, then Create your own application. Name it, for example "Clock Clerk provisioning", choose Integrate any other application you don't find in the gallery (Non-gallery), and create it.
Open its Provisioning page and set the provisioning mode to Automatic. Under Admin Credentials, enter the SCIM address as the Tenant URL and the token as the Secret Token. Choose Test Connection, then save.
Under Mappings, set Provision Microsoft Entra ID Groups to No: Clock Clerk does not take groups. Leave Provision Microsoft Entra ID Users on, with its default mappings. Attributes Clock Clerk does not keep, such as department, manager, phone numbers and addresses, are accepted and set aside (see below).
Under Settings, set Scope to Sync only assigned users and groups. Then, on the application's Users and groups page, assign the people or groups who should be in Clock Clerk. Assigning a group sends its members.
Back on Provisioning, set Provisioning Status to On and save.

The first cycle sends everybody in scope. After it, Entra ID sends changes about every 40 minutes. To send one person now, use Provision on demand on the Provisioning page.

Entra ID sends each person's user principal name, the name they sign in with, as their Clock Clerk address. In an organization that signs in with Microsoft, that is the address their sign-in finds them by, even where their mailbox is a different address. In an organization that signs in another way, people are found by their email address instead, so where the two differ, change the mapping for userName to take mail rather than userPrincipalName.

What Clock Clerk takes from the provider

The provider's attribute	In Clock Clerk
`userName`	The person's email address, which is what their sign-in finds them by. It has to be an address.
`name` or `displayName`	Their name: the full name if sent, then the display name, then the given and family names together.
`title`	Their Job title.
`emails`	Checked against `userName` where your organization does not sign in with Microsoft. Not stored separately.
`active`	Whether they are still here: turning it off sets their Left date (see below).
`externalId`	The provider's own id for them, so it can find them again. Nobody else here can have the same one.

Anything else the provider sends, such as a department, a manager, phone numbers, addresses or a preferred language, is accepted and set aside. Role, grants, projects and the Started date are never the provider's: they are set on People.

When the provider and the People tab disagree

A name corrected in Clock Clerk is kept. Once an administrator renames somebody on People, the provider's spelling no longer replaces it, just as signing in again does not.
The provider wins on the rest of what it sends. A job title changed on People is replaced by the provider's at its next update of that person, so change it at the provider instead.
Leaving is the provider's to say. A Left date set on People ends the person's access as it always does. But if the provider later sends them as active, a Left date that has already passed is cleared, because the provider is where people are managed. A date still to come is left alone.
Somebody added by hand and then sent by the provider stays one person: the provider takes them over, and their history, role and grants stay theirs.

What deactivating somebody does

In Okta, deactivating somebody or unassigning them from the app deactivates them in Clock Clerk. In Entra ID, so does disabling their account, removing them from the application, or deleting them. Clock Clerk then:

Sets their Left date to yesterday, so their access has ended at once rather than at midnight.
Signs them out everywhere. Their next step in the app, and every sign-in after, is refused with Your access has ended.
Keeps everything they did: their weeks, approvals, expenses, invoices and messages stay, as for anybody whose Left date was set on People (see When somebody leaves).

Reactivating or reassigning them in the provider clears the Left date, and they can sign in again. When Entra ID deletes somebody for good, Clock Clerk also stops treating them as the provider's, so if somebody is later provisioned at that address, they take over the same person, with their history.

The provider cannot deactivate your organization's last administrator who is still here, because only an administrator can revoke a token or bring anybody back. Make somebody else an administrator first.

When something goes wrong

The provider shows each person it could not send, with Clock Clerk's reason. The usual ones:

userName and the primary email differ: in an organization that does not sign in with Microsoft, people are matched by their email, so the username the provider sends has to be it. In Okta, set the Application username format to Email; in Entra ID, map mail to userName.
userName has to be the person's email address: the provider sent something that is not an address.
Already provisioned here, or somebody else here is already at an address: two people at the provider have the same address, or the person was provisioned before under another id. Fix the address at the provider.
A guest of this organization: the address belongs to a client guest. An administrator converts the guest on People, and the provider's next try then takes them over.
Last administrator: see above.

If the provider is refused entirely, check that the token has not been revoked on the Provisioning tab and that your organization is still on the Enterprise plan. Tokens are kept on other plans but stop working there.