SCIM Concepts and Shared Setup

AuthOS SCIM is Beta. The examples describe implemented paths, not certification or guaranteed interoperability with every identity-provider release.

What is SCIM?

SCIM (System for Cross-domain Identity Management) is an industry-standard protocol for automating user lifecycle management. With SCIM, your identity provider (IdP) can:

• Automatic Provisioning: Create users when added to the directory
• Profile Sync: Update user information when changed in the IdP
• Deprovisioning: Deactivate or remove users when they leave
• Group Management: Synchronize group memberships across systems

Prerequisites

Before setting up SCIM provisioning:

1. Organization Admin Access: You need admin access to your AuthOS organization
2. IdP Administrator Role: Admin access to your identity provider (Okta, Azure AD, OneLogin, etc.)
3. HTTPS Endpoint: AuthOS must be accessible via HTTPS
4. SDK Installed (optional): npm install @drmhse/sso-sdk for programmatic token management

Step 1: Generate a SCIM Token

SCIM tokens authenticate requests from your identity provider to AuthOS.

Using the SDK

import { SsoClient } from '@drmhse/sso-sdk';

const sso = new SsoClient({
  baseURL: 'https://sso.example.com',
  token: 'your-org-admin-jwt'
});

// Create a SCIM token
const scimToken = await sso.organizations.scim.createToken('acme-corp', {
  name: 'Okta SCIM Integration'
});

console.log('SCIM Base URL:', 'https://sso.example.com/scim/v2');
console.log('Bearer Token:', scimToken.token);

// IMPORTANT: Save this token securely - it's only shown once

Using the API Directly

curl -X POST https://sso.example.com/api/organizations/acme-corp/scim-tokens \
  -H "Authorization: Bearer your-org-admin-jwt" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Okta SCIM Integration",
    "expires_at": "2026-12-31T23:59:59Z"
  }'

Response:

{
  "id": "scim-token-123",
  "name": "Okta SCIM Integration",
  "token": "scim_live_abc123def456...",
  "prefix": "scim_live_abc1",
  "created_at": "2025-01-15T10:00:00Z",
  "expires_at": "2026-12-31T23:59:59Z"
}

Critical: The full token is only shown once. Store it securely in your identity provider.

Advanced Configuration

Automatic Token Rotation

Implement automatic token rotation for security:

async function rotateScimToken(orgSlug: string, oldTokenId: string) {
  // Create new token
  const newToken = await sso.organizations.scim.createToken(orgSlug, {
    name: 'Okta SCIM Integration - Rotated'
  });

  console.log('Update your IdP with this token:', newToken.token);

  // After updating IdP configuration, revoke old token
  // await sso.organizations.scim.revokeToken(orgSlug, oldTokenId);

  return newToken;
}

// Schedule token rotation every 6 months

Custom Attribute Mapping

Some organizations need custom attribute mappings:

// Example: Azure AD custom security attributes
// In Azure AD provisioning mappings, add:
// extensionAttribute1 -> emails[type eq "work"].value
// customAttribute -> name.formatted

Handling Provisioning Conflicts

When a user already exists (e.g., manually created before SCIM):

// The IdP will receive a 409 Conflict error
// Options:
// 1. Delete the manual user first
// 2. Configure IdP to update instead of create
// 3. Use matching rules in IdP to link existing users

For Azure AD, configure Accidental Deletions Threshold to prevent mass deprovisioning:

1. Navigate to Provisioning → Settings
2. Set Accidental deletions threshold to 5-10 users
3. Azure AD will pause and alert if deletions exceed threshold

Filtering Users for Provisioning

Control which users get provisioned using IdP filters:

Okta: Use group assignments to scope users

Azure AD: Use scoping filters in provisioning settings:

department Equals "Engineering"
city Equals "San Francisco"

OneLogin: Use provisioning rules with conditions

Security Best Practices

Token Management

1. Rotate Tokens Regularly: Rotate SCIM tokens every 6-12 months
2. Use Expiration Dates: Set expiration dates on tokens to force rotation
3. Limit Token Scope: Each IdP integration should have its own token
4. Monitor Token Usage: Alert on unused or suspicious token activity
5. Revoke Unused Tokens: Remove tokens that haven’t been used in 90+ days

Access Control

1. Least Privilege: Only grant SCIM provisioning to necessary IdP administrators
2. Audit Logging: Review SCIM provisioning logs regularly
3. IP Allowlisting (if supported): Restrict SCIM endpoint access to IdP IP ranges
4. HTTPS Only: Never use HTTP for SCIM endpoints

Data Protection

1. Soft Deletion: Use active: false instead of hard deletion for compliance
2. PII Handling: Ensure IdP-to-SSO data transfer complies with regulations (GDPR, CCPA)
3. Backup Before Bulk Operations: Back up user data before enabling provisioning
4. Test in Staging: Test SCIM configuration in a non-production environment first

Next steps

Choose an identity-provider recipe, then complete Validation.