Pre-release — content may change.

GuidesSingle Sign-OnDelegated Authentication

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

ParameterTypeRequiredDescription
provider_slugstringYesSlug of configured SSO provider
external_idstringYesUser's unique ID from identity provider
emailstringYesUser's email address
email_typestringNoEmail type (work, personal, etc.). Default: personal
replace_primary_emailbooleanNoReplace primary email if person found by external_id. Default: false
person.given_namestringNoFirst name (for new users only)
person.family_namestringNoLast 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/linked
  • 201 Created — New user identity created
  • 409 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:

  1. No person found with email newuser@example.com
  2. No user identity found with external_id: new-user-123
  3. Create new person with provided attributes
  4. Create new email as primary
  5. Create new user identity linking to person
  6. Ensure user role granted
  7. 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:

  1. Person found with email existing@example.com
  2. No user identity found with external_id: existing-user-456
  3. Create new user identity for existing person
  4. Ensure user role granted
  5. 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:

  1. No person found with email newemail@example.com
  2. User identity found with external_id: user-789 (linked to person A)
  3. Create new email on person A as primary
  4. Previous primary email retained as unique email
  5. Return 200 OK

Result: Person A now has additional email address.

With replace_primary_email: true:

  1. Existing primary email updated to newemail@example.com
  2. 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:

  1. Person found with email same@example.com
  2. User identity found with external_id: user-999 belonging to same person
  3. No action needed — identity already linked correctly
  4. Ensure user role granted
  5. 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:

  1. Person B found with email personb@example.com
  2. User identity with external_id: user-111 found, but linked to person A
  3. Transfer user identity from person A to person B
  4. Ensure person B has user role
  5. 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

AspectSSO Provisioning (/user_identities/provision)Local Creation (POST /people)
Called ByMiddleware iPaaS (in response to webhooks)Your application (user sign-up forms)
Email ConflictsAutomatically handled — links to existing personReturns 409 — requires explicit claiming
User IdentityAlways created/linkedNot created (unless SSO added later)
External IDRequiredNot applicable
ProviderRequired (provider_slug)Not applicable
Conflict StrategySmart matching by email + external_idManual 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

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 identity

4. 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;
  }
}

On this page