This article explains how to configure SCIM (System for Cross-domain Identity Management) with Okta so you can automatically provision, update, and deprovision Hubstaff members from your Okta directory. You can also map Okta groups to Hubstaff teams.

SCIM handles provisioning. It does not handle how people sign in. If you want your team to sign in through Okta, set up SSO as well. See How SCIM and SSO work together below. For SCIM with other providers, see the Microsoft Entra ID and OneLogin articles, or contact us at support@hubstaff.com.

How SCIM and SSO work together

SCIM and SSO do two different jobs, and they are independent of each other:

SCIM provisions accounts. It creates and updates members and their profile details in Hubstaff. It does not send passwords to Hubstaff and does not control how people sign in.

SSO handles sign-in. With SSO, users sign in through Okta.

You can use SCIM on its own, but we recommend setting up both SCIM and SSO:

• With SSO enabled, provisioned users sign in through Okta, and you do not manage their passwords in Hubstaff.
• Without SSO, each provisioned user still needs a Hubstaff password. You set and manage that password for every provisioned user in Hubstaff. To avoid this manual step, set up SSO.

To set up SSO, see How to configure Single Sign-on.

Before you start

• An Enterprise plan and an account with Organization Owner, Organization Manager, or the Manage IT permission.
• Administrator access to your Okta organization.
• Recommended: SSO configured for your organization, so provisioned users can sign in through Okta without a Hubstaff password. The Okta SAML application configured below can also provide the SSO connection.

Enable SCIM in Hubstaff

In Hubstaff, go to Settings > Organization > Security & log in.

Open the Single Sign-on & SCIM tab, then turn on the Enable SCIM toggle.

Copy the SCIM URL and SCIM token. You will paste both into Okta.

Create the Okta application

In the Okta Admin Console, go to Applications and Resources > Applications > Create App Integration, select SAML 2.0, and continue.

In the SAML settings, enter the values from your Hubstaff SSO settings. See How to configure Single Sign-on for instructions on locating these values:

• Single sign-on URL = your Hubstaff Reply URL
• Audience URI (SP Entity ID) = your Hubstaff Identifier
• Name ID format = EmailAddress
• Application username = Email

Turn on SCIM provisioning in Okta

Open the application’s General tab. Select Edit next to App Settings, enable SCIM provisioning, then select Save.

Go to the Provisioning tab, select Edit next to SCIM Connection, and enter the following settings:

• SCIM connector base URL = your Hubstaff SCIM URL
• Unique identifier field for users = userName
• Under Supported Provisioning Actions, enable:
  • Import New Users and Profile Updates
  • Push New Users
  • Push Profile Updates
  • Push Groups
  • Import Groups
• Authentication Mode = HTTP Header
• Authorization = your Hubstaff SCIM token

Select Test Connector Configuration to verify the connection, then select Save.

Under Provisioning > To App, enable Create Users, Update User Attributes, and Deactivate Users.

Add the OS username attribute

Hubstaff stores an OS username for each member, and Okta does not send one by default. Add a custom attribute to the Hubstaff application’s profile, then map it to the user’s email so Okta sends it. Complete these steps before assigning users so the OS username is included in the first push.

From the application page, go to Provisioning, scroll down to Attribute Mappings, then select Go to Profile Editor > Add Attribute and enter:

• Data type = string
• Display name = osUsername
• Variable name = osUsername
• External name = osUsername
• External namespace = urn:ietf:params:scim:schemas:extension:hubstaff:2.0:User
• Attribute required = Yes
• Attribute type = Personal
• Mutability = Read/Write

Save the attribute.

In the Profile Editor, select Mappings, then select Okta User to Hubstaff. Map user.email to osUsername, then save the mapping. Okta adds an app-specific prefix to this attribute, so the full name may appear as <your-app>.osUsername.

Provisioning users

Use the application’s Assignments tab under your new application to assign people. When you assign someone, Okta creates their Hubstaff member or links an existing member with the same email address.

Once assigned, the member appears on your Hubstaff People > Members page. These profile fields sync from Okta: display name, first name, last name, email, job title, department, employee ID, and OS username.

Updating users

When you change a member’s profile in Okta, such as their job title or department, the update syncs to Hubstaff. Fields you do not change stay as they are.

De-provisioning users

To remove a member, unassign the application from them in Okta or deactivate their Okta account. They are removed from your Hubstaff organization and its teams. Reassigning the application restores their membership.

Mapping Okta groups to Hubstaff teams

You can mirror Okta groups as Hubstaff teams. Before pushing groups:

1. Turn on Map SCIM groups to teams in your Hubstaff SSO/SCIM settings.

2. Push each group manually from the application’s Push Groups tab in Okta.

When you push a group, Hubstaff creates a matching team. If the group name matches an existing Hubstaff team that is not already SCIM-managed, Hubstaff uses the existing team instead of creating a duplicate. Renaming the group renames the team, and adding or removing group members updates its membership. Team membership updates are not instant, so allow a short delay before checking the team in Hubstaff.

Managing and disconnecting SCIM

To stop SCIM provisioning, turn off the Enable SCIM toggle. A confirmation dialog appears; select Disconnect to confirm. Disconnecting deletes the SCIM token and removes the SCIM link from your members and teams. Your members and teams keep their names, team memberships, and tracked data. Only the connection to your identity provider is removed.

If you re-enable SCIM later, Hubstaff generates a new SCIM token, and the old one stops working, so update Okta with the new token. Map SCIM groups to teams starts turned off again after reconnecting, even if it was enabled before.

Troubleshooting and FAQ

A provisioned user can’t sign in to Hubstaff.

SCIM creates the account but does not set a way to sign in. If your organization uses SSO, the user signs in through Okta with Log in with SSO. If you do not use SSO, go to People > Members. Next to the member, select Actions > Reset password. Choose Automatically generate password to view and copy a generated password in the next step, or select Create password to set one manually. Share the password with the member through a secure channel. You can also set up SSO so they can sign in through Okta. See How SCIM and SSO work together above.

Should I enable Sync Password in Okta?

No. Hubstaff does not use passwords pushed from Okta, so leave this setting off.

Do I have to set up SSO to use SCIM?

No. SCIM and SSO are independent. We recommend setting up both so you do not have to manage passwords manually in Hubstaff.

I pushed an Okta group, but no Hubstaff team appeared.

Turn on Map SCIM groups to teams in Hubstaff before pushing the group, then push it from the application’s Push Groups tab. Team membership updates are not instant, so allow a short delay.