User Provisioning
Understanding user provisioning flows, conflict handling, and account claiming
User provisioning links external identity provider accounts to Wicket person records using the /user_identities/provision API endpoint.
Who calls this API?
- CAS-Proxied Delegation: Middleware iPaaS calls this (not your application)
- Direct Integration: Your application calls this during login
See Delegated Authentication Guide to understand the two approaches.
Who Calls This API?
It depends on your integration approach:
CAS-Proxied Delegation
Middleware iPaaS calls /user_identities/provision to sync users:
Your application does NOT call this endpoint. Your app uses standard CAS authentication.
Direct Integration
Your application calls /user_identities/provision during the login flow:
Your application handles provisioning as part of the login flow.
Provisioning Endpoint
API Request (Called by Middleware iPaaS)
POST /user_identities/provision
Content-Type: application/vnd.api+json
Authorization: Bearer YOUR_ADMIN_JWT_TOKEN # Middleware iPaaS admin token{
"data": {
"type": "user_identities",
"attributes": {
"provider_slug": "b2c",
"external_id": "30e165a2-4b5c-4dee-b8ff-cd7eac8f8f65",
"email": "john@example.com",
"email_type": "work",
"replace_primary_email": false,
"person": {
"given_name": "John",
"family_name": "Doe"
}
},
"relationships": {
"user_identity_provider": {
"data": {
"type": "user_identity_providers",
"id": "provider-uuid"
}
}
}
}
}Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
provider_slug | string | Yes | Slug of configured SSO provider |
external_id | string | Yes | User's unique ID from identity provider |
email | string | Yes | User's email address |
email_type | string | No | Email type (work, personal, etc.). Default: personal |
replace_primary_email | boolean | No | Replace primary email if person found by external_id. Default: false |
person.given_name | string | No | First name (for new users only) |
person.family_name | string | No | Last name (for new users only) |
Response (Success)
{
"data": {
"id": "user-identity-uuid",
"type": "user_identities",
"attributes": {
"provider_slug": "b2c",
"provider_name": "Azure AD B2C",
"provider_type": "generic_oidc",
"external_id": "30e165a2-4b5c-4dee-b8ff-cd7eac8f8f65",
"created_at": "2025-01-17T10:00:00Z",
"updated_at": "2025-01-17T10:00:00Z"
},
"relationships": {
"person": {
"data": { "type": "people", "id": "person-uuid" }
},
"user": {
"data": { "type": "users", "id": "user-uuid" }
}
}
},
"included": [
{
"type": "people",
"id": "person-uuid",
"attributes": {
"given_name": "John",
"family_name": "Doe",
"primary_email_address": "john@example.com"
}
}
]
}Status Codes:
200 OK— Existing user identity updated/linked201 Created— New user identity created409 Conflict— Email already exists (see Email Conflicts)422 Unprocessable Entity— Validation errors
Provisioning Flow (Middleware iPaaS)
This flow shows how middleware iPaaS calls the provisioning endpoint to link external identities:
Flow Scenarios
Scenario 1: New User (No Email, No Identity)
Request:
{
"provider_slug": "b2c",
"external_id": "new-user-123",
"email": "newuser@example.com",
"person": {
"given_name": "Jane",
"family_name": "Smith"
}
}Process:
- No person found with email
newuser@example.com - No user identity found with
external_id: new-user-123 - Create new person with provided attributes
- Create new email as primary
- Create new user identity linking to person
- Ensure user role granted
- Return
201 Created
Result: New person created with user identity attached.
Scenario 2: Existing Email, No Identity
Request:
{
"provider_slug": "b2c",
"external_id": "existing-user-456",
"email": "existing@example.com" // Email already exists in Wicket
}Process:
- Person found with email
existing@example.com - No user identity found with
external_id: existing-user-456 - Create new user identity for existing person
- Ensure user role granted
- Return
201 Created
Result: Existing person now has SSO identity attached.
Scenario 3: Identity Exists, Different Email
Request:
{
"provider_slug": "b2c",
"external_id": "user-789", // Already linked to a person
"email": "newemail@example.com", // Different email
"replace_primary_email": false
}Process:
- No person found with email
newemail@example.com - User identity found with
external_id: user-789(linked to person A) - Create new email on person A as primary
- Previous primary email retained as unique email
- Return
200 OK
Result: Person A now has additional email address.
With replace_primary_email: true:
- Existing primary email updated to
newemail@example.com - Previous primary email replaced (not retained)
Scenario 4: Identity Exists, Same Email
Request:
{
"provider_slug": "b2c",
"external_id": "user-999", // Already linked to person with this email
"email": "same@example.com"
}Process:
- Person found with email
same@example.com - User identity found with
external_id: user-999belonging to same person - No action needed — identity already linked correctly
- Ensure user role granted
- Return
200 OK
Result: No changes, existing linkage confirmed.
Scenario 5: Transfer Identity
Request:
{
"provider_slug": "b2c",
"external_id": "user-111", // Linked to person A
"email": "personb@example.com" // Belongs to person B
}Process:
- Person B found with email
personb@example.com - User identity with
external_id: user-111found, but linked to person A - Transfer user identity from person A to person B
- Ensure person B has user role
- Return
200 OK
Result: User identity moved from person A to person B.
Identity Transfer: When a user identity is transferred from one person to another, the original person (A) loses the SSO linkage. This typically happens when email ownership changes or during account migrations.
Email Conflicts
When creating a new person locally (without SSO), email conflicts must be handled explicitly.
Local User Creation Flow
409 Conflict Response
When creating a person via POST /people (not the provision endpoint), an email conflict returns:
{
"errors": [
{
"status": "409",
"code": "taken",
"title": "Email address already exists",
"detail": "The email address is already in use",
"meta": {
"field": "emails.address",
"error": "taken",
"claimable": true,
"taken_by": {
"id": "existing-person-uuid",
"type": "people"
}
}
}
]
}Claiming Existing Accounts
When meta.claimable is true, the account can be claimed by updating it:
async function handleEmailConflict(createError) {
const error = createError.errors.find(e =>
e.meta?.field === 'emails.address' &&
e.meta?.error === 'taken'
);
if (!error) {
throw createError;
}
// Check if claimable
if (!error.meta.claimable) {
throw new Error('Email already in use and cannot be claimed');
}
// Claim existing person by updating with user attributes
const personId = error.meta.taken_by.id;
const response = await fetch(`${WICKET_API}/people/${personId}`, {
method: 'PATCH',
headers: {
'Authorization': `Bearer ${adminToken}`,
'Content-Type': 'application/vnd.api+json'
},
body: JSON.stringify({
data: {
id: personId,
type: 'people',
attributes: {
user_attributes: {
email: userEmail,
password: userPassword,
password_confirmation: userPassword
}
}
}
})
});
return response.json();
}Example: Sign-Up with Conflict Handling
async function createUserAccount(email, password, firstName, lastName) {
try {
// Attempt to create new person
const response = await fetch(`${WICKET_API}/people`, {
method: 'POST',
headers: {
'Authorization': `Bearer ${adminToken}`,
'Content-Type': 'application/vnd.api+json'
},
body: JSON.stringify({
data: {
type: 'people',
attributes: {
given_name: firstName,
family_name: lastName,
user: {
email: email,
password: password,
password_confirmation: password
}
},
relationships: {
emails: {
data: [{
type: 'emails',
attributes: {
address: email,
primary: true,
type: 'personal'
}
}]
}
}
}
})
});
if (response.status === 201) {
// Success!
return await response.json();
}
if (response.status === 409) {
// Email conflict - try claiming
const errorData = await response.json();
return await handleEmailConflict(errorData);
}
throw new Error(`Unexpected status: ${response.status}`);
} catch (error) {
console.error('User creation failed:', error);
throw error;
}
}SSO vs Local User Creation
Key Differences
| Aspect | SSO Provisioning (/user_identities/provision) | Local Creation (POST /people) |
|---|---|---|
| Called By | Middleware iPaaS (in response to webhooks) | Your application (user sign-up forms) |
| Email Conflicts | Automatically handled — links to existing person | Returns 409 — requires explicit claiming |
| User Identity | Always created/linked | Not created (unless SSO added later) |
| External ID | Required | Not applicable |
| Provider | Required (provider_slug) | Not applicable |
| Conflict Strategy | Smart matching by email + external_id | Manual claiming flow |
When to Use Each
Use /user_identities/provision:
Via middleware (CAS-Proxied):
- SSO delegated authentication (CAS → B2C/Auth0/Okta)
- Middleware syncing users between Wicket and external IdPs
- Webhook-driven provisioning flows
- Not called by application during login
In application (Direct Integration):
- Direct OIDC/SAML integration with external providers
- Application manages OAuth applications
- Called by application during login callback
Use POST /people (in application):
- Local username/password registration forms
- User self-service sign-up
- Manual user creation by administrators
- No SSO integration
Code Examples (Middleware iPaaS)
These examples show how middleware iPaaS calls the provisioning endpoint. This is NOT application code.
Important: Your application does not call these endpoints during login. Your application implements standard CAS authentication (see SSO Guide).
Node.js Middleware
const fetch = require('node-fetch');
async function provisionSSOUser(ssoUserData) {
const response = await fetch(
`${process.env.WICKET_API_URL}/user_identities/provision`,
{
method: 'POST',
headers: {
'Authorization': `Bearer ${process.env.WICKET_ADMIN_TOKEN}`,
'Content-Type': 'application/vnd.api+json'
},
body: JSON.stringify({
data: {
type: 'user_identities',
attributes: {
provider_slug: 'b2c',
external_id: ssoUserData.sub,
email: ssoUserData.email,
person: {
given_name: ssoUserData.given_name,
family_name: ssoUserData.family_name
}
}
}
})
}
);
return await response.json();
}
// Usage
const result = await provisionSSOUser({
sub: 'user-123-from-b2c',
email: 'john@example.com',
given_name: 'John',
family_name: 'Doe'
});
console.log('Person ID:', result.data.relationships.person.data.id);
console.log('Status:', response.status === 201 ? 'Created' : 'Updated');async function provisionSSOUserSafely(ssoUserData) {
try {
const response = await fetch(
`${process.env.WICKET_API_URL}/user_identities/provision`,
{
method: 'POST',
headers: {
'Authorization': `Bearer ${process.env.WICKET_ADMIN_TOKEN}`,
'Content-Type': 'application/vnd.api+json'
},
body: JSON.stringify({
data: {
type: 'user_identities',
attributes: {
provider_slug: 'b2c',
external_id: ssoUserData.sub,
email: ssoUserData.email,
person: {
given_name: ssoUserData.given_name,
family_name: ssoUserData.family_name
}
}
}
})
}
);
const data = await response.json();
if (!response.ok) {
if (response.status === 409) {
console.error('Email conflict:', data.errors);
throw new Error('Email already exists');
} else if (response.status === 422) {
console.error('Validation errors:', data.errors);
throw new Error('Invalid user data');
} else {
throw new Error(`Provisioning failed: ${response.status}`);
}
}
return {
userIdentity: data.data,
person: data.included?.find(r => r.type === 'people'),
isNew: response.status === 201
};
} catch (error) {
console.error('SSO provisioning error:', error);
throw error;
}
}const express = require('express');
const app = express();
// Middleware iPaaS webhook handler (NOT application code)
app.post('/webhooks/wicket/roles-granted', async (req, res) => {
try {
// 1. Receive webhook from Wicket
const { person, roles } = req.body.data.attributes;
console.log(`Received roles.granted webhook for person ${person.id}`);
// 2. Create user in external provider (e.g., Azure B2C)
const b2cUser = await createB2CUser({
email: person.primary_email_address,
givenName: person.given_name,
surname: person.family_name,
displayName: `${person.given_name} ${person.family_name}`
});
console.log(`Created B2C user: ${b2cUser.id}`);
// 3. Provision user identity in Wicket
const provisionResult = await provisionSSOUser({
sub: b2cUser.id, // B2C user ID
email: person.primary_email_address,
person_id: person.id
});
console.log(`Provisioned user identity: ${provisionResult.data.id}`);
// 4. Acknowledge webhook
res.status(200).json({ success: true });
} catch (error) {
console.error('Webhook processing error:', error);
res.status(500).json({ error: error.message });
}
});
async function createB2CUser(userData) {
// Create user in Azure B2C using Microsoft Graph API
const response = await fetch('https://graph.microsoft.com/v1.0/users', {
method: 'POST',
headers: {
'Authorization': `Bearer ${process.env.B2C_ADMIN_TOKEN}`,
'Content-Type': 'application/json'
},
body: JSON.stringify({
accountEnabled: true,
displayName: userData.displayName,
mailNickname: userData.email.split('@')[0],
userPrincipalName: `${userData.email}@your-tenant.onmicrosoft.com`,
passwordProfile: {
forceChangePasswordNextSignIn: true,
password: generateRandomPassword()
},
givenName: userData.givenName,
surname: userData.surname,
mail: userData.email
})
});
return await response.json();
}Best Practices
1. Include Related Resources
Fetch person data along with user identity:
// Add ?include=person to get person data in response
const response = await provisionUser({
...userData,
include: 'person,user'
});
// Person data available in included array
const person = response.included.find(r => r.type === 'people');2. Store External ID for Future Lookups
Cache the external ID for quick lookups:
// After provisioning
const externalId = result.data.attributes.external_id;
const personId = result.data.relationships.person.data.id;
// Store mapping for quick lookups
await cacheSet(`sso:${providerSlug}:${externalId}`, personId);
// Later, check cache before provisioning
const cachedPersonId = await cacheGet(`sso:${providerSlug}:${externalId}`);
if (cachedPersonId) {
// Skip provisioning, use cached person ID
}3. Handle Idempotency
Provisioning is idempotent — safe to call multiple times:
// Safe to call on every SSO login
const result = await provisionUser(ssoUserData);
// Returns 200 if identity exists, 201 if created
// Either way, you get the user identity4. Monitor Provisioning Metrics
Track success/failure rates:
async function provisionWithMetrics(userData) {
const start = Date.now();
try {
const result = await provisionUser(userData);
metrics.record('sso.provision.success', {
provider: userData.provider_slug,
duration: Date.now() - start,
status: result.status
});
return result;
} catch (error) {
metrics.record('sso.provision.failure', {
provider: userData.provider_slug,
error: error.message
});
throw error;
}
}