Just-In-Time User Provisioning

User provisioning

Provisioning is the process of creating a user and setting attributes for them inside an app.

JIT user provisioning

Just-in-time user provisioning creates a user in an app when the user attempts to sign in for the first time. The account and respective role don’t exist until the app creates them – just-in-time.

Identity

An identity is a collection of attributes associated with a user or entity in an identity provider. For example, an identity includes at least one unique identifier, such as id, and user profile attributes, such as name and email.

Role

A primitive in your app that defines specific permissions for the users. Roles are often defined as an ability or a job title, for example, “Editor” or “Accountant”.

User provisioning is the process of creating a user account with associated identity data in an application. The application needs to determine a unique identifier for an identity, create a unique account for that user, and link the identity profile attributes to that user’s account. There are many strategies to provision users in an app, but the main three are:

1. Self-registration
2. Provisioning users via Directory Sync
3. JIT provisioning via SSO

The type of provisioning needed depends on the app’s architecture and level of enterprise feature support:

JIT provisioning creates a user account with associated identity information when a user authenticates via SSO for the first time. IT admins often use JIT provisioning to quickly set up accounts in an app. Typically, apps that implement only SSO will have JIT provisioning support as the alternative is self-registration by individual users or manual entry of all users by the IT admin.

Consider the fictional SaaS company HireOS, which offers recruiting software to other businesses. HireOS is an online app allowing customers to track leads, candidates, and interviews.

HireOS has integrated SSO using WorkOS and supports JIT provisioning. For example, a HireOS customer would like their users to have accounts automatically provisioned in HireOS when they first log in. The customer’s IT admin will only need to assign the users to the HireOS SAML app in their identity provider. When users log into HireOS via SSO, they will have accounts created in HireOS, just in time.

A usual account setup flow using JIT provisioning follows these steps:

1. An IT admin self-registers via username and password to create a team account in HireOS.
2. The IT admin configures the HireOS team account to use SSO as the authentication mechanism.
3. The IT admin enables JIT provisioning for this team account by clicking the “Enable JIT Provisioning” checkbox.
4. The IT admin adds the users that should get access to HireOS to the app in the identity provider.
5. When a user logs into HireOS with the correct email domain and authenticates via SSO, HireOS creates the user account upon successful first-time login.

When a user authenticates to an application via SSO for the first time, and JIT provisioning is enabled, the application provisions a new user account. The account can be created by saving the identity information (the WorkOS SSO profile) directly on the app’s user account. Alternatively, a separate identity can be created from the WorkOS SSO profile and related to the new user account. This logic allows users to have multiple identities if the app supports several login methods per user.

The WorkOS SSO profile id attribute serves as the unique identifier for this identity from WorkOS. WorkOS ensures the profile is unique per SSO connection via the idp_id. In addition, the app can use either the connection_id or organization_id to tie the identity to a team account.

{
  "object": "profile",
  "id": "prof_01DMC79VCBZ0NY2099737PSVF1",
  "connection_id": "conn_01E4ZCR3C56J083X43JQXF3JK5",
  "connection_type": "OktaSAML",
  "organization_id": "org_01EHWNCE74X7JSDV0X3SZ3KJNY",
  "email": "todd@example.com",
  "first_name": "Todd",
  "last_name": "Rundgren",
  "idp_id": "00u1a0ufowBJlzPlk357",
  "role": {
    "slug": "admin"
  }
}

Applications may want to grant new users roles via JIT provisioning. For more information on mapping role data between the IdP and the application, see the Mapping Roles guide.

When an application receives a WorkOS SSO profile, the standard practice is to perform the following series of checks:

1. Find an identity with the profile id or idp_id. If found, log in the corresponding user.
2. If no identity is found, try to find a user with the same email as the profile. If found, create an identity for the user and log them in.
3. Otherwise, create a new identity using the WorkOS SSO profile, create a new user, and associate this identity with the user account.

If an admin adds SSO authentication to their team account after users have already registered, the application can link these new SSO identities to the current user accounts, just-in-time.

A linking field (e.g. email) should be established to find a current user with the incoming WorkOS SSO Profile. The identity information can then be linked with the existing user account via a persistent identifier in case of an email change later.

This document offers guidance on integrating Single Sign-On with the standalone API into an existing auth stack. AuthKit is also available as a complete authentication platform that leverages Single Sign-On functionality out of the box, following best practices.