Automated user provisioning

Automatically create users from third-party identity providers in identity pools. This happens instantly when users sign in for the first time.

💡 Why this matters
Reduces manual user management while giving you better control over authentication and user data.

Why use automated provisioning

Organizations that use third-party identity providers to sign in to the platform or protected applications can enable automatic user provisioning for:

Unified User Representation: See all users in one place, whether they sign in locally or through third-party identity providers. This gives you better visibility into all users accessing applications or the admin portal.

Attribute Augmentation: Add extra user information like permissions, roles, and relationships to accounts from external providers. This helps you make better authorization decisions and assign user roles locally.

Operational Attribute Capture: Track user activity like last sign-in time, even for users from external identity providers. This helps you keep accurate records of user activity.

Hybrid Authentication Support: Use external identity providers for the first authentication step, then let the platform handle the second factor. This gives you stronger authentication with better control over multi-factor authentication.

How automated user provisioning works

The diagram shows when and how automated user provisioning happens.

Authentication and provisioning steps:

1. User accesses application → Clicks the sign in button

   • The application can be the SecureAuth platform itself

2. Application sends OAuth request → Calls SecureAuth OAuth /authorize endpoint

3. User goes to login page → SecureAuth login page appears

4. External authentication → User picks a third party identity provider and signs in

5. Return to application → User gets sent back to the application

6. User lookup by federation ID → SecureAuth looks up the user by the federation identifier

   • This gets much faster after the user signs in at least once
   • The federation identifier is a hashed IDP identifier : original IDP subject (sub)

7. Update existing user → If SecureAuth finds the user, it updates their information

8. Check for matching accounts → If SecureAuth doesn't find the user, it checks for existing accounts to prevent duplicates

   • SecureAuth looks for users with the same email address or other matching information
   • This prevents creating two accounts for the same person from different identity providers
   • If SecureAuth finds a match, it updates that user's information

9. Create new user → If no match is found, SecureAuth creates a new user account in the configured identity pool

10. Log the event → SecureAuth sends an audit event

⚠️ Security note
SecureAuth logs audit events when users are created, updated, or when provisioning fails.

Email and phone verification

When creating users in identity pools, email and phone numbers need verification. Here's part of the Create User API that shows how this works:

"verifiable_addresses": [
   {
      "address": "string",
      "address_lc": "string",
      "created_at": "2019-08-24T14:15:22Z",
      "id": "string",
      "preferred_contact_method": "sms",
      "status": "active",
      "tenant_id": "default",
      "type": "mobile",
      "updated_at": "2019-08-24T14:15:22Z",
      "user_id": "string",
      "user_pool_id": "default",
      "verified": true,
      "verified_at": "2019-08-24T14:15:22Z"
   }
]            

The user has an array of verifiable_addresses, where each address is a separate JSON object.

When users get created with information from their authentication, you can control whether their email or phone number needs verification. You can configure user attributes so email or phone gets added to the user's verifiable_addresses object.

Verification options for email and phone:

Option	Verification Behavior	Use Case
Email/Phone verified	Takes value from authentication, sets verified flag to true	Trusted identity providers
Email/Phone unverified	Takes value from authentication, sets verified flag to false	Requires local verification
Email/Phone OIDC Discovery	Takes value from authentication, gets verified flag from OIDC standard claim (email_verified or phone_number_verified)	OIDC-based identity providers with standard claims

Next step: Configure provisioned attributes from third-party providers