Single sign-on and SCIM

With single sign-on, people at your company sign in to Usertick through your identity provider, such as Okta, Microsoft Entra ID or Google Workspace. With SCIM, the provider also adds people to your organization and removes them when they leave. Single sign-on and SCIM are available on the Business plan. Only the owner of the organization sees and changes them, under Settings → Developers → SSO and SCIM.

​

Before you start

• Your organization is on the Business plan, and you are its owner.
• You can create apps in your identity provider.
• You can add a DNS record to your company’s email domain.

An organization has one single sign-on connection, for one email domain. Usertick signs in only addresses at exactly that domain: with usertick.com as the domain, [email protected] signs in through the provider, and [email protected] doesn’t.

​

When single sign-on is on

Single sign-on signs people in after three things are true:

1. The connection to your identity provider is saved.
2. The email domain is verified.
3. A test sign-in succeeded with the provider details as they are saved now.

The line at the bottom of the page says where it stands. “Single sign-on is on for addresses at domain.” means people can sign in. Until then it says “Single sign-on turns on when steps 1 to 4 are done.” When the plan no longer includes single sign-on, it says “Single sign-on is off because the plan doesn’t include it.”, and Usertick keeps the settings.

​

Set up single sign-on

The page walks through six steps and marks each one as done or needing attention. The first save is Connect in step 2. After that, changes to the provider details, the domain and the sign-in rules wait in the bar at the bottom of the page until you select Save changes. With two-factor authentication on, saving and disconnecting ask for a code.

​

Add Usertick to your identity provider

Select your provider in step 1: Okta, Microsoft Entra ID, Google Workspace, OneLogin, JumpCloud or Other SAML. The step then shows the values to paste, labeled with the names your provider uses, and the provider’s own steps beside them. The steps for each provider are under Identity provider settings.

​

Give Usertick the provider’s details

Step 2 takes the provider’s issuer, sign-in URL and signing certificate in one of three ways:

• Metadata URL. Paste the metadata URL from your provider and select Read metadata. The URL must start with https and be reachable from the internet.
• Upload metadata file. Choose the metadata file your provider exported, up to 1 MB.
• Enter the details by hand. Fill in Issuer, Sign-in URL and Certificate. The sign-in URL must start with https. Paste the X.509 certificate in PEM format, and to add more than one, paste each certificate in full.

Reading the metadata fills in the details and saves nothing. Usertick takes the sign-in URL for the HTTP-Redirect binding and up to three signing certificates, newest first, and shows each certificate’s fingerprint and expiry date. When the metadata lists more signing certificates, or expired ones beside a valid one, the step says how many it leaves out. Then enter your Email domain, such as usertick.com, and select Connect. When Usertick can’t read the metadata or save the details, the step says why:

​

Verify the email domain

Usertick signs in only addresses at a domain that your organization proves it owns. After you connect, step 3 shows a DNS record: After the check, step 3 says “domain is verified.” Keep the record in place: every test sign-in checks it again. An email domain can be verified by one organization only. Changing the email domain later needs a new record and a new verification.

​

Test the sign-in

Step 4 checks the connection end to end before anyone depends on it. The test runs every check a real sign-in runs: the signature, the issuer, the audience, the response’s destination, the time window, and an email address at your domain. It signs nobody in to Usertick and creates no account. A successful test shows the address that signed in and the names of the attributes your provider sent, such as “Attributes received: email, firstName, lastName.”. A failed test says why and what to change. The test is available after the domain is verified, and it uses the saved details, so save your changes first. It has to finish within 10 minutes of starting. Changing the issuer, the sign-in URL, the certificates or the email domain turns single sign-on off until a new test succeeds. Usertick asks before it saves such a change while single sign-on is on. Until the next test succeeds, people at your domain sign in with a password or Google, and people who sign in only through single sign-on can’t sign in.

​

Sign-in rules

Step 5 sets how people at your domain sign in. The rules save with the connection. A person with a pending invitation to your organization joins with the invitation’s role, and the invitation counts as accepted.

​

Require single sign-on

While single sign-on is on and required, Usertick refuses these for every address at your domain:

• Signing in with a password.
• Signing in or signing up with Google, and linking Google to an account.
• Finishing a new sign-up with the email code.
• Setting a password. Forgot password? sends no reset link.

The refused screen says “Your organization requires single sign-on for this address. Select Continue to sign in through your identity provider.” and opens the single sign-on step with the address filled in. The requirement applies to every account at the domain, including accounts that aren’t members of your organization. The owner is the exception: the owner keeps a password and Google, so the owner can still sign in when the provider is down. The requirement takes effect at each person’s next sign-in, and devices that are already signed in stay signed in. Usertick asks before it turns the requirement on, and applies it only while single sign-on is on. When the provider details or the domain change, the requirement stays on, and Usertick applies it again after the next successful test.

​

How people sign in

1. On the Usertick sign-in page, the person selects Sign in with SSO.
2. They enter their Work email and select Continue.
3. Usertick sends them to your identity provider, and after they sign in there, back to Usertick, signed in.

The sign-in page remembers the account, so the next time it offers the account as one tile that goes straight to the provider. Usertick reads the person’s email address from the email, mail, Email or User.Email attribute, or from the email address claim that Microsoft Entra ID sends. When none of these holds an address, Usertick uses the Name ID if it is an email address. The address must be at your verified domain. For a new account, the name comes from the displayName attribute, or from firstName and lastName. A sign-in through single sign-on doesn’t ask for a Usertick two-factor code. Your identity provider’s own checks, such as its multi-factor authentication, apply instead. When a sign-in can’t finish, the sign-in page explains why. See Sign-in error messages.

​

Sign in from your provider’s dashboard

People can also open Usertick from the Usertick app tile in your identity provider’s dashboard, such as the Okta End-User Dashboard or Microsoft My Apps. Usertick checks the provider’s response with the same certificates, audience, destination and time window as any sign-in, then starts a normal sign-in through the provider for your domain. The provider already has a session, so it answers at once, and the person lands in Usertick signed in. The response from the tile creates no account or membership and signs nobody in by itself. The sign-in that follows does, under your sign-in rules. Signing in from the tile works while single sign-on is on; otherwise the person sees “Single sign-on for this domain isn’t turned on yet. Ask your administrator to finish the setup.”

​

Provisioning with SCIM

With SCIM, your identity provider adds people to Usertick when it assigns them the Usertick app, and removes them when it unassigns or deactivates them. SCIM is optional and needs a verified email domain. After that, step 6 shows the base URL, how the token starts, when and by whom it was created, and the time of the provider’s last request.

​

What SCIM does

Usertick refuses to add an address outside your verified domain, a person who is already a member, anyone past the plan’s member limit, and an existing account that is suspended, already being deleted, or scheduled for deletion by its person. An account that single sign-on or SCIM created can always come back, and its scheduled deletion is canceled. The owner is never removed or deactivated through SCIM: transfer the ownership in Settings → Organization first. SCIM in Usertick covers users. Groups aren’t provisioned, so turn off group push in your provider, and every new person gets the default role or their invitation’s role. Each token can make 600 requests a minute.

​

The changes list

Beside the provisioning details, Changes lists what your provider changed in the last 7 days, with an exact count for each kind, and refreshes while the page is open. It lists the latest 50 changes, such as “Usertick added [email protected] as Member.” or “[email protected] is now [email protected].”, and says so when the week had more. When the changes can’t be read, the list says they aren’t available right now. A refused change says why:

​

Rotate or turn off the token

• Rotate token creates a new token after you confirm. The current token stops working at once, and provisioning pauses until the new token is in your provider.
• Turn off deletes the token after you type how it starts. The provider can no longer add or remove people, and the members it added stay.

With two-factor authentication on, generating, rotating and turning off ask for a code.

​

Identity provider settings

Each section below follows step 1 for one provider. Copy the values from step 1 of the setup in Usertick: they are the same for every provider, under the provider’s own names.

​

Okta

To provision with SCIM:

1. On the General tab, select Edit under App Settings, set Provisioning to SCIM and select Save.
2. On the Provisioning tab, under Settings → Integration, select Edit.
3. Paste the base URL into the SCIM connector base URL field and enter userName as the unique identifier field for users.
4. Under Supported provisioning actions, select Push New Users and Push Profile Updates. Leave Push Groups off.
5. Set Authentication Mode to HTTP Header, paste the API token into Authorization, and save.
6. Under Settings → To App, turn on creating users, updating user attributes and deactivating users, and save.

When Okta unassigns or deactivates a person, it deactivates them in Usertick, so a later assignment restores their membership.

​

Microsoft Entra ID

To provision with SCIM:

1. In the Usertick app, open Provisioning and start a new configuration. In the older layout, set Provisioning Mode to Automatic.
2. Paste the base URL into Tenant URL and the API token into Secret Token, and select Test Connection.
3. Under the attribute mapping for users, check that userName receives the user’s work email address. When users’ principal names differ from their email addresses, map mail to userName. Turn off the mapping for groups.
4. Save, then select Start provisioning.

Entra provisions the users and groups assigned to the app and syncs about every 40 minutes. When a user is unassigned or blocked, Entra deactivates them in Usertick.

​

Google Workspace

Test the connection with Test sign-in in Usertick. Google Workspace provisions users automatically only for the apps in its own catalog, so a custom SAML app such as Usertick has no SCIM settings in Google. With Google Workspace, turn on Create accounts on first sign-in and remove people in Settings → People. Step 6 in Usertick says so, and Generate a token for another tool remains for a provisioning tool other than Google.

​

OneLogin

To provision with SCIM:

1. On the Configuration tab, paste the base URL into SCIM Base URL and the API token into SCIM Bearer Token, enable the API connection, and select Save.
2. On the Parameters tab, set SCIM Username to the email address.
3. On the Provisioning tab, turn on provisioning. When a user is deleted or loses access, Suspend deactivates them in Usertick, so they can be restored later, and Delete removes them without a record.

​

JumpCloud

To provision with SCIM:

1. Open the app’s provisioning settings (Identity Management or Provisioning, depending on the Admin Portal version).
2. Paste the base URL into Base URL and the API token into the token field.
3. Enter a Test User Email at your verified domain that has no Usertick account, and select Test Connection.
4. Turn off the management of user groups and group membership.
5. Select Activate.

On activation, JumpCloud creates, updates and deletes the test user in Usertick, so the changes list shows that user as added and removed. When a user is unbound, JumpCloud deactivates them in Usertick.

​

Other identity providers

Any identity provider that supports SAML 2.0 works. Create a SAML app in it with these settings:

• ACS URL: the assertion consumer service URL from step 1, with the HTTP-POST binding.
• Entity ID or audience: the entity ID from step 1.
• Name ID: the user’s work email address, in the email address format.
• Attributes: email, firstName and lastName.
• Signing: sign the response, the assertion or both.

Then give Usertick the provider’s metadata URL or file. Usertick needs the provider’s entity ID, a sign-in URL for the HTTP-Redirect binding that starts with https, and its signing certificate. When the provider offers no metadata, enter these three by hand. A provider that sets the app up from a file can read Usertick’s metadata from Download metadata in step 1. For SCIM, the provider needs SCIM 2.0 with a bearer token. Usertick supports the Users resource with create, read, replace, update and delete, and looks people up by userName, externalId, id or email address with the eq operator. Groups and bulk requests aren’t supported.

​

Rotate certificates

Your identity provider signs each sign-in with a certificate that expires after a number of years that the provider sets. Step 2 shows each saved certificate’s expiry date, and marks an expired certificate and a step without a current one. Usertick accepts a sign-in signed by any of up to three saved certificates, so you can add the new certificate before the provider switches to it:

​

Disconnect single sign-on

Disconnect at the bottom of the page removes the connection after you type the email domain. Then:

• Your team can no longer sign in through your provider.
• People who signed in only through single sign-on, which the dialog counts, can’t sign in until they set a password with Forgot password? on the sign-in page.
• Provisioning stops, and the SCIM token stops working.
• Require single sign-on turns off.

Members stay in the organization with their roles.

​

Sign-in error messages

When single sign-on can’t start or finish, the sign-in page shows one of these messages:

​

FAQ