SurePassID Platform Workflows

SurePassID Authentication Server

SurePassID Platform Workflows

Version: 2025.4
Date: January 2025
Author: SurePassID Engineering

Overview

This document catalogs every distinct business workflow in the SurePassID platform. A workflow is an end-to-end business process with a clear trigger, a sequence of steps (possibly spanning multiple API calls, UI interactions, and background operations), and a defined outcome.

Workflows are not the same as API calls. A single workflow typically involves multiple API endpoints, database operations, and user interactions. Conversely, a single API endpoint (e.g., validate_oath_otp) may participate in several different workflows.

How to Read This Document

Each workflow is documented with:

• Trigger — What initiates the workflow
• Actors — Who or what participates (Admin, User, System, External Service)
• Steps — The ordered sequence of operations
• Data Flow — Key tables and records created/modified
• Outcome — The end state
• API Endpoints — REST endpoints involved (if any)
• Sequence Diagram — Visual flow (for complex workflows)

Workflow Categories

1. User Authentication Workflows

These workflows verify a user's identity. Each combines a primary factor (usually credentials) with a second factor (OTP, Push, FIDO, etc.).

1.1 — Credential + OTP Authentication

Trigger: User submits username and password to authenticate.
Actors: End User, Client Application, MFA Server

Steps:

User                    Client App              MFA Server                    Database
 │                          │                       │                            │
 │── enter credentials ────>│                       │                            │
 │                          │── validate_user ─────>│                            │
 │                          │                       │── verify password ─────────>│
 │                          │                       │<── user record ────────────│
 │                          │                       │── check Bypass MFA flag    │
 │                          │                       │   (if set, skip 2FA)       │
 │                          │<── success + methods ─│                            │
 │                          │                       │                            │
 │                          │── send_oath_otp ─────>│                            │
 │                          │   (type: sms|email|   │── generate temp OTP ──────>│
 │                          │    voice)             │── send via SMS/Email/Voice │
 │                          │<── OTP sent ──────────│                            │
 │                          │                       │                            │
 │── enter OTP ────────────>│                       │                            │
 │                          │── validate_oath_otp ─>│                            │
 │                          │                       │── verify OTP match ────────>│
 │                          │                       │── write audit record ──────>│
 │                          │                       │── update device counter ───>│
 │                          │<── auth success ──────│                            │
 │<── logged in ────────────│                       │                            │

Data Flow:

• Reads: PartnerUser, Device (OTP seed, counter), PartnerSettings (OTP config)
• Writes: PartnerUserAudit (auth result, IP, method), Device (next counter, last validation)

API Endpoints: validate_user, send_oath_otp, validate_oath_otp

1.2 — Credential + Push Authentication

Trigger: User submits credentials; system sends push notification to mobile app.
Actors: End User, Client Application, MFA Server, Mobile Authenticator App, Push Notification Service (APNs/FCM)

Steps:

User          Client App         MFA Server            Push Service        Mobile App
 │                │                   │                      │                  │
 │── login ──────>│                   │                      │                  │
 │                │── validate_user ─>│                      │                  │
 │                │<── success ───────│                      │                  │
 │                │                   │                      │                  │
 │                │── send_push ─────>│                      │                  │
 │                │   _message        │── push notification ─>│                  │
 │                │                   │   (via APNs/FCM)      │── display ──────>│
 │                │<── push sent ─────│                      │   approve/deny   │
 │                │                   │                      │                  │
 │                │                   │                      │<── user taps ────│
 │                │                   │                      │    approve       │
 │                │                   │<── tap_auth_response ─│                  │
 │                │                   │── store response ────>│(DB)              │
 │                │                   │                      │                  │
 │                │── is_user_push ──>│                      │                  │
 │                │   _authenticated  │── check response ───>│(DB)              │
 │                │<── approved ──────│                      │                  │
 │<── logged in ──│                   │                      │                  │

Data Flow:

• Reads: MobilePushNotification (push tokens), PartnerUser (push challenge)
• Writes: PartnerUser.Push Token (challenge), PartnerUserAudit

API Endpoints: validate_user, send_push_message, tap_auth_response, is_user_push_authenticated

Notes:

• The client polls is_user_push_authenticated until the user responds or timeout
• Push type is determined by MobilePushNotification.Push Type (0=APNs, 1=FCM)
• The ApnsTopic column determines the iOS bundle identifier for the notification
• If the push includes FIDO signing, SigningPublicKey and SignChallenge on MobilePushNotification are used

1.3 — Credential + FIDO U2F Authentication

Trigger: User submits credentials; server challenges a registered U2F security key.
Actors: End User, Browser, MFA Server

Steps:

1. User submits credentials → validate_user → success
2. Client requests challenge → pre_sign → server returns challenge + registered key handles
3. Browser calls U2F API with challenge → user touches security key
4. Client submits signed assertion → sign → server verifies signature against stored public key
5. Auth success → audit logged

Data Flow:

• Reads: DeviceFIDOApp (public key, key handle), Device (U2F device record)
• Writes: DeviceFIDOApp (sign counter incremented), PartnerUserAudit

API Endpoints: validate_user, pre_sign, sign

1.4 — FIDO2/WebAuthn Two-Factor Authentication

Trigger: User submits credentials; server challenges a registered FIDO2 authenticator.
Actors: End User, Browser (WebAuthn API), MFA Server

Steps:

1. User submits credentials → validate_user → success
2. Client requests assertion options → /api/fido/v2/assertion/options → server returns challenge + allowCredentials list
3. Browser calls navigator.credentials.get() → user provides gesture (touch/PIN/biometric)
4. Client submits assertion result → /api/fido/v2/assertion/result → server verifies signature, checks sign counter
5. Auth success → audit logged

Data Flow:

• Reads: DeviceFIDOApp (credential ID, public key, AAGUID, sign counter)
• Writes: DeviceFIDOApp (sign counter), PartnerUserAudit

API Endpoints: validate_user, /api/fido/v2/assertion/options, /api/fido/v2/assertion/result

1.5 — FIDO2 Passwordless Authentication

Trigger: User initiates login without entering a username — the FIDO2 resident key identifies the user.
Actors: End User, Browser (WebAuthn API), MFA Server

Steps:

1. Client requests assertion options without a username → /api/fido/v2/assertion/options
2. Server returns challenge with empty allowCredentials (resident key discovery)
3. Browser calls navigator.credentials.get() → authenticator presents resident credential → user provides gesture
4. Client submits assertion result → /api/fido/v2/assertion/result
5. Server identifies user from userHandle in the assertion → verifies signature
6. Auth success → single-step login complete → audit logged

Key Difference from 1.4: No validate_user call — the user is both identified and authenticated by the FIDO2 credential in a single step.

API Endpoints: /api/fido/v2/assertion/options, /api/fido/v2/assertion/result

1.6 — Bypass MFA Authentication

Trigger: Admin has set the Bypass MFA flag on a user account (e.g., during onboarding or for a service account).
Actors: End User, Client Application, MFA Server

Steps:

1. User submits credentials → validate_user
2. Server verifies password → checks PartnerUser.[Bypass MFA] flag
3. Flag is set → second factor is skipped entirely
4. Auth success → audit logged with AuthenticationMethodId = 5 (Bypass MFA)

Data Flow:

• Reads: PartnerUser.[Bypass MFA]
• Writes: PartnerUserAudit (method = Bypass MFA)

API Endpoints: validate_user

Notes: This is typically a temporary state set by an admin. The admin portal allows setting this flag per-user.

2. User Provisioning & Lifecycle Workflows

These workflows cover how user accounts are created, imported, synchronized, and managed throughout their lifecycle.

2.1 — Manual User Creation (Admin Portal)

Trigger: Admin clicks "Add User" in the SurePassID admin portal.
Actors: Admin, Admin Portal UI, MFA Server

Steps:

Admin                   Admin Portal              MFA Server              Database
 │                          │                         │                      │
 │── click "Add User" ─────>│                         │                      │
 │                          │── display user form ───>│                      │
 │── fill in fields:        │                         │                      │
 │   - Login Name           │                         │                      │
 │   - Password             │                         │                      │
 │   - First/Last Name      │                         │                      │
 │   - Email                │                         │                      │
 │   - Cell Phone           │                         │                      │
 │   - Admin Privilege      │                         │                      │
 │   - Group                │                         │                      │
 │── click "Create" ───────>│                         │                      │
 │                          │── INSERT PartnerUser ──>│                      │
 │                          │                         │── hash password ────>│
 │                          │                         │── create PartnerUser │
 │                          │                         │                      │
 │                          │   (if admin role)       │                      │
 │                          │── INSERT Dashboard ────>│                      │
 │                          │                         │── create default     │
 │                          │                         │   dashboard items    │
 │                          │                         │                      │
 │                          │   (if send welcome)     │                      │
 │                          │── send notification ───>│                      │
 │                          │                         │── resolve template   │
 │                          │                         │   (Enroll or         │
 │                          │                         │    LoginInformation) │
 │                          │                         │── send email ───────>│(SMTP)
 │                          │                         │                      │
 │<── user created ─────────│                         │                      │

Data Flow:

• Creates: PartnerUser record, PartnerUserEmail (if email provided), PartnerUserDashboard (if admin)
• Reads: PartnerSettings (password policy), NotificationTemplate (welcome email)

2.2 — User Creation via REST API

Trigger: External system calls the add_user or add_oath_user API endpoint.
Actors: External System, MFA Server

Steps:

1. External system sends add_user request with user details + API credentials
2. Server validates API key against PartnerApi table and checks ApiPermission (ID 12: AddUser)
3. Server creates PartnerUser record with hashed password
4. If add_oath_user: also creates a Device record (OATH token) and assigns it to the user
5. Returns user ID and status

API Endpoints: add_user, add_oath_user, /api/admin/user/create

Data Flow:

• Validates: PartnerApi (API key), ApiPermission + ApiEndpoint (authorization)
• Creates: PartnerUser, optionally Device + assignment

2.3 — CSV Bulk User Import (Admin Portal)

Trigger: Admin uploads a CSV file through the admin portal to create or update multiple users at once.
Actors: Admin, Admin Portal UI, MFA Server

Steps:

Admin                   Admin Portal              MFA Server              Database
 │                          │                         │                      │
 │── navigate to            │                         │                      │
 │   Import Users page ────>│                         │                      │
 │                          │── display upload form   │                      │
 │                          │                         │                      │
 │── select CSV file ──────>│                         │                      │
 │   (columns: LoginName,   │                         │                      │
 │    Password, FirstName,  │                         │                      │
 │    LastName, Email,      │                         │                      │
 │    CellPhone, Group,     │                         │                      │
 │    AdminPrivilege)       │                         │                      │
 │                          │                         │                      │
 │── click "Import" ───────>│                         │                      │
 │                          │── parse CSV rows ──────>│                      │
 │                          │                         │                      │
 │                          │   FOR EACH ROW:         │                      │
 │                          │   ┌─────────────────────┤                      │
 │                          │   │ validate fields     │                      │
 │                          │   │ (required, format,  │                      │
 │                          │   │  duplicate check)   │                      │
 │                          │   │                     │                      │
 │                          │   │ IF user exists:     │                      │
 │                          │   │   UPDATE PartnerUser│                      │
 │                          │   │ ELSE:               │                      │
 │                          │   │   INSERT PartnerUser│                      │
 │                          │   │   hash password     │                      │
 │                          │   │   create email rec  │                      │
 │                          │   └─────────────────────┤                      │
 │                          │                         │                      │
 │                          │── generate import ─────>│                      │
 │                          │   results summary       │                      │
 │                          │                         │                      │
 │<── results displayed:    │                         │                      │
 │    - X users created     │                         │                      │
 │    - Y users updated     │                         │                      │
 │    - Z rows failed       │                         │                      │
 │    - error details       │                         │                      │

CSV Format:

LoginName,Password,FirstName,LastName,Email,CellPhone,Group,AdminPrivilege
john.doe,P@ssw0rd!,John,Doe,john@example.com,+15551234567,Sales,N
jane.smith,S3cure#1,Jane,Smith,jane@example.com,+15559876543,Engineering,Y

Data Flow:

• Creates/Updates: PartnerUser, PartnerUserEmail
• Validates: Duplicate login names within tenant, email format, password policy compliance
• Audit: Bulk import logged to PartnerUserAudit

Error Handling:

• Invalid rows are skipped and reported in the results summary
• Valid rows in the same file are still processed (partial success allowed)
• Duplicate login names within the CSV are flagged as errors

2.4 — AD/LDAP User Import (Admin Portal)

Trigger: Admin configures an LDAP/Active Directory connection in the admin portal and initiates a manual import of users.
Actors: Admin, Admin Portal UI, MFA Server, LDAP/AD Server

Steps:

Admin                Admin Portal           MFA Server            LDAP/AD Server      Database
 │                       │                      │                      │                │
 │── configure LDAP ────>│                      │                      │                │
 │   connection:         │                      │                      │                │
 │   - Server URL        │                      │                      │                │
 │   - Base DN           │                      │                      │                │
 │   - Bind credentials  │                      │                      │                │
 │   - Search filter     │                      │                      │                │
 │   - Attribute mapping │                      │                      │                │
 │                       │                      │                      │                │
 │── click "Test" ──────>│                      │                      │                │
 │                       │── LDAP bind ────────>│                      │                │
 │                       │                      │── LDAP bind ────────>│                │
 │                       │                      │<── bind success ─────│                │
 │                       │── search query ─────>│                      │                │
 │                       │                      │── LDAP search ──────>│                │
 │                       │                      │<── user entries ─────│                │
 │<── preview: N users   │                      │                      │                │
 │    found              │                      │                      │                │
 │                       │                      │                      │                │
 │── click "Import" ────>│                      │                      │                │
 │                       │── full LDAP search ─>│                      │                │
 │                       │                      │── paginated search ─>│                │
 │                       │                      │<── all entries ──────│                │
 │                       │                      │                      │                │
 │                       │   FOR EACH AD USER:  │                      │                │
 │                       │   ┌──────────────────┤                      │                │
 │                       │   │ map attributes:  │                      │                │
 │                       │   │  sAMAccountName  │                      │                │
 │                       │   │   → LoginName    │                      │                │
 │                       │   │  givenName       │                      │                │
 │                       │   │   → FirstName    │                      │                │
 │                       │   │  sn → LastName   │                      │                │
 │                       │   │  mail → Email    │                      │                │
 │                       │   │  mobile          │                      │                │
 │                       │   │   → CellPhone    │                      │                │
 │                       │   │  memberOf        │                      │                │
 │                       │   │   → Group        │                      │                │
 │                       │   │                  │                      │                │
 │                       │   │ IF user exists:  │                      │                │
 │                       │   │  UPDATE fields   │                      │                │
 │                       │   │ ELSE:            │                      │                │
 │                       │   │  CREATE user     │                      │                │
 │                       │   │  generate pwd    │                      │                │
 │                       │   │                  │                      │                │
 │                       │   │ IF AD disabled:  │                      │                │
 │                       │   │  disable in SP   │                      │                │
 │                       │   └──────────────────┤                      │                │
 │                       │                      │                      │                │
 │<── import complete:   │                      │                      │                │
 │    - X created        │                      │                      │                │
 │    - Y updated        │                      │                      │                │
 │    - Z disabled       │                      │                      │                │

AD Attribute Mapping (Default):

Data Flow:

• Reads: LDAP/AD directory via LDAP protocol (port 389/636)
• Creates/Updates: PartnerUser, PartnerUserEmail
• Disables: Users whose AD accounts are disabled or deleted

Notes:

• This is a manual, one-time import — not ongoing sync (see Workflow 2.5)
• Password is auto-generated since AD passwords cannot be read
• Admin can optionally send welcome emails to imported users
• The connection settings are stored in PartnerSettings for reuse by Directory Sync

2.5 — Directory Sync (Scheduled AD/LDAP Synchronization)

Trigger: Scheduled task or admin-initiated sync that continuously keeps SurePassID users in sync with Active Directory / LDAP.
Actors: MFA Server (background process), LDAP/AD Server, External Sync Agent (optional)

Steps:

Scheduler/Agent         MFA Server              LDAP/AD Server           Database
 │                          │                        │                      │
 │── directory_sync_start ─>│                        │                      │
 │   (API call or           │                        │                      │
 │    scheduled trigger)    │                        │                      │
 │                          │── LDAP connect ───────>│                      │
 │                          │<── connected ──────────│                      │
 │                          │                        │                      │
 │                          │── incremental search ─>│                      │
 │                          │   (uSNChanged ≥ last   │                      │
 │                          │    sync watermark)     │                      │
 │                          │<── changed entries ────│                      │
 │                          │                        │                      │
 │                          │   FOR EACH CHANGED USER:                      │
 │                          │   ┌────────────────────┤                      │
 │                          │   │                    │                      │
 │                          │   │ CASE: new in AD    │                      │
 │                          │   │  → CREATE user     │─────────────────────>│
 │                          │   │    in SurePassID   │                      │
 │                          │   │                    │                      │
 │                          │   │ CASE: modified     │                      │
 │                          │   │  → UPDATE fields   │─────────────────────>│
 │                          │   │    (name, email,   │                      │
 │                          │   │     phone, group)  │                      │
 │                          │   │                    │                      │
 │                          │   │ CASE: disabled     │                      │
 │                          │   │  → SET disabled    │─────────────────────>│
 │                          │   │    date on user    │                      │
 │                          │   │                    │                      │
 │                          │   │ CASE: deleted      │                      │
 │                          │   │  → disable user    │─────────────────────>│
 │                          │   │    (preserve       │                      │
 │                          │   │     audit trail)   │                      │
 │                          │   └────────────────────┤                      │
 │                          │                        │                      │
 │                          │── update sync          │                      │
 │                          │   watermark ──────────>│(store last           │
 │                          │                        │ uSNChanged)          │
 │                          │                        │                      │
 │                          │── write audit ────────>│                      │
 │                          │   (sync summary)       │                      │
 │                          │                        │                      │
 │<── sync complete ────────│                        │                      │
 │    (X created,           │                        │                      │
 │     Y updated,           │                        │                      │
 │     Z disabled)          │                        │                      │

Key Behaviors:

• Incremental sync: Uses AD uSNChanged attribute to only process changes since last sync
• Disable, never delete: When an AD account is deleted, the SurePassID user is disabled (not deleted) to preserve audit history and token assignments
• Group mapping: AD memberOf maps to SurePassID Group assignments
• Conflict resolution: AD is authoritative — AD values overwrite SurePassID values for synced fields

API Endpoints: directory_sync_start

Data Flow:

• Reads: LDAP/AD, PartnerSettings (LDAP config, sync watermark)
• Creates/Updates/Disables: PartnerUser, PartnerUserEmail
• Writes: PartnerUserAudit (sync events)

2.6 — Directory Sync + Automatic Token Assignment & Activation

Trigger: Directory sync creates a new user, and the tenant is configured to automatically assign and activate tokens for new users.
Actors: MFA Server (background process), LDAP/AD Server, Notification Service

This extends Workflow 2.5 with automatic token provisioning:

Steps:

Directory Sync          MFA Server              Notification Svc         Database
 │                          │                        │                      │
 │── new user synced ──────>│                        │                      │
 │   from AD                │                        │                      │
 │                          │── CREATE PartnerUser ─>│                      │
 │                          │                        │                      │
 │                          │── check PartnerSettings│                      │
 │                          │   auto-provision config│                      │
 │                          │                        │                      │
 │                          │   IF auto-provision enabled:                   │
 │                          │   ┌────────────────────┤                      │
 │                          │   │                    │                      │
 │                          │   │ 1. CREATE Device   │                      │
 │                          │   │    (mobile auth    │─────────────────────>│
 │                          │   │     token, type=9) │                      │
 │                          │   │    Generate seed   │                      │
 │                          │   │    Set OTP params  │                      │
 │                          │   │    Set Usage flags │                      │
 │                          │   │    (MobileUsageFlags)                     │
 │                          │   │                    │                      │
 │                          │   │ 2. ASSIGN device   │                      │
 │                          │   │    to user         │─────────────────────>│
 │                          │   │    (Assigned       │                      │
 │                          │   │     Partner User Id)                      │
 │                          │   │                    │                      │
 │                          │   │ 3. Generate        │                      │
 │                          │   │    activation URL  │                      │
 │                          │   │    (QR code +      │                      │
 │                          │   │     deep link)     │                      │
 │                          │   │                    │                      │
 │                          │   │ 4. Send activation │                      │
 │                          │   │    notification ──>│                      │
 │                          │   │                    │── resolve template   │
 │                          │   │                    │   (ActivateDevice    │
 │                          │   │                    │    or                │
 │                          │   │                    │    ActivateDeviceSms)│
 │                          │   │                    │── send email/SMS ───>│(SMTP/Twilio)
 │                          │   │                    │                      │
 │                          │   └────────────────────┤                      │
 │                          │                        │                      │
 │                          │── write audit ────────>│                      │
 │                          │   (user created,       │                      │
 │                          │    token assigned,     │                      │
 │                          │    activation sent)    │                      │

What the User Receives:

• Email or SMS with activation instructions
• Contains a URL like: surepassid://activate?code=ABC123&issuer=CompanyName
• User opens SurePassID Authenticator app → scans QR or taps link → token activated

Subsequent User Action (Token Activation):

User                    Mobile App              MFA Server              Database
 │                          │                       │                      │
 │── open activation link ─>│                       │                      │
 │   or scan QR code        │                       │                      │
 │                          │── provision_push ─────>│                     │
 │                          │   _device              │── register push ───>│
 │                          │                        │   token (APNs/FCM)  │
 │                          │                        │── set Device status │
 │                          │                        │   to Active         │
 │                          │                        │── set Push Provision│
 │                          │                        │   Date              │
 │                          │<── provisioned ────────│                     │
 │                          │                        │                     │
 │                          │── active_oath_device ─>│                     │
 │                          │                        │── verify activation │
 │                          │                        │   code matches      │
 │                          │                        │── set Device status │
 │                          │                        │   to Active         │
 │                          │<── activated ──────────│                     │
 │<── ready to use ─────────│                        │                     │

Data Flow:

• Creates: Device (token), MobilePushNotification (push registration)
• Updates: Device (status → Active, Push Provision Date, Push Provision Token)
• Reads: PartnerSettings (token config, issuer name, usage flags)

2.7 — Password Recovery

Trigger: User clicks "Forgot Password" on the login page.
Actors: End User, Login Page, MFA Server, Notification Service

Steps:

1. User enters username or email → submits forgot password request
2. send_password_recovery → server generates time-limited recovery token
3. Stores token + expiration in PartnerUser.Password Recovery Token and Password Recovery Token Expiration Date
4. Sends email via PasswordReset notification template with reset link
5. User clicks link → enters new password
6. password_recovery_change_password → server validates token, hashes new password, clears recovery token
7. Sends PasswordChanged notification to user
8. Audit logged

API Endpoints: send_password_recovery, password_recovery_change_password

2.8 — Account Lockout & Unlock

Trigger: User exceeds MaxFailedUsernamePasswordLoginAttempts (default 10) consecutive failed login attempts.
Actors: End User, MFA Server, Admin, Notification Service

Steps:

1. Each failed validate_user increments PartnerUser.FailedUsernamePasswordLoginAttempts
2. When count reaches PartnerSettings.MaxFailedUsernamePasswordLoginAttempts:
   • Account is locked (disabled)
   • AccountLocked notification sent to user (email)
   • SecurityAlert notification sent to admin
   • Audit logged with severity = ActionRequired
3. Admin reviews alert → navigates to user edit page → clicks "Unlock Account"
4. System resets FailedUsernamePasswordLoginAttempts to 0, clears disabled date
5. AccountUnlocked notification sent to user

Data Flow:

• Reads/Writes: PartnerUser.FailedUsernamePasswordLoginAttempts, PartnerUser.Disabled Date
• Reads: PartnerSettings.MaxFailedUsernamePasswordLoginAttempts

3. Token Lifecycle Workflows

3.1 — Mobile Token Provisioning (Email/SMS Activation)

Trigger: Admin assigns a mobile authenticator token to a user and sends activation instructions.
Actors: Admin, MFA Server, Notification Service, End User, Mobile Authenticator App

Steps:

1. Admin creates mobile token in portal (Device Type = 9, MobileAuthenticator)
2. System generates OATH seed (secret key), sets OTP parameters
3. Admin assigns token to user (assign_device)
4. Admin clicks "Send Activation" → send_device_activation
5. System generates activation URL with embedded provisioning code
6. Sends via email (ActivateDevice template) or SMS (ActivateDeviceSms template)
7. User opens link in SurePassID Authenticator → scans QR code
8. App calls provision_push_device → registers push token (APNs/FCM)
9. App calls active_oath_device → confirms activation with OTP
10. Token status set to Active

API Endpoints: send_device_activation, provision_push_device, active_oath_device

Data Flow:

• Creates: Device, MobilePushNotification
• Updates: Device (status, Push Provision Date, Usage)

3.2 — Hardware Token Import & Assignment

Trigger: Admin imports hardware tokens from a PSKC (Portable Symmetric Key Container) XML file.
Actors: Admin, Admin Portal, MFA Server

Steps:

1. Admin navigates to Token Import page
2. Uploads PSKC XML file (contains serial numbers, seeds, OTP parameters)
3. Server parses PSKC → creates Device records for each token (status = Available)
4. Tokens appear in token inventory
5. Admin assigns individual tokens to users (assign_device)
6. User activates by entering a valid OTP from the hardware token (active_oath_device)

Data Flow:

• Creates: Device records (one per hardware token in the PSKC file)
• Updates: Device.Assigned Partner User Id, Device.Status

3.3 — FIDO2/U2F Key Registration

Trigger: User or admin initiates FIDO security key enrollment.
Actors: End User, Browser, MFA Server

Steps (FIDO2):

1. Client requests attestation options → /api/fido/v2/attestation/options
2. Server generates challenge, specifies RP info and user info
3. Browser calls navigator.credentials.create() → user provides gesture
4. Client submits attestation result → /api/fido/v2/attestation/result
5. Server validates attestation, extracts public key, stores credential
6. Creates DeviceFIDOApp record with credential ID, public key, AAGUID, sign counter
7. Creates/updates Device record (Device Type = 12, FIDO)

API Endpoints: /api/fido/v2/attestation/options, /api/fido/v2/attestation/result
Legacy U2F: pre_enroll, enroll

3.4 — OTP Sync (Counter Resynchronization)

Trigger: A hardware HOTP token's counter has drifted out of the server's look-ahead window (user pressed the button without authenticating).
Actors: End User or Admin, MFA Server

Steps:

1. User/admin provides two consecutive OTP values from the token
2. sync_oath_device → server searches the counter space for both OTPs in sequence
3. If found, counter is reset to the matched position
4. Future OTP validations succeed again

API Endpoints: sync_oath_device, /api/auth/otp/sync

3.5 — Token Decommissioning

Trigger: Admin removes a token from service (user departure, lost token, token expiration).
Actors: Admin, MFA Server

Steps:

1. Admin disables token → disable_device → Device.Status set to Disabled
2. Admin unassigns from user → unassign_device → Device.Assigned Partner User Id set to NULL
3. Admin deletes token → delete_device → Device record removed
4. DeviceFIDOApp records cascade-deleted (FK with ON DELETE CASCADE)
5. MobilePushNotification records for this device are cleaned up
6. Audit trail preserved in PartnerUserAudit

API Endpoints: disable_device, unassign_device, delete_device

4. PIV Smart Card Workflows

4.1 — PIV Certificate Enrollment

Trigger: User or admin enrolls a PIV smart card by registering its X.509 certificate.
Actors: End User (with PIV card + reader), Browser/Agent, MFA Server

Steps:

1. Client requests enrollment challenge → piv_pre_enroll
2. Server generates random nonce, creates PivAuthSession (state = Pending)
3. Client signs the nonce with the PIV card's private key (Key Slot 9A = Authentication)
4. Client submits signed response + certificate chain → piv_enroll
5. Server validates:
   • Certificate chain (up to PivTrustedCA roots)
   • Certificate not expired (NotBefore / NotAfter)
   • Revocation status (CRL or OCSP via CrlDistributionPoint / OcspResponder)
   • Signature over nonce is valid
6. Creates Device (Type = 15, PivSmartCard) + DevicePivCertificate record
7. Assigns device to user

API Endpoints: piv_pre_enroll, piv_enroll
Admin Batch: piv_admin_enroll (registers cert without challenge-response, admin-only)

Data Flow:

• Creates: Device, DevicePivCertificate (cert blob, hash, subject/issuer DN, FASC-N, UUID)
• Reads: PivTrustedCA (trusted certificate authorities for this tenant)

4.2 — PIV Challenge-Response Authentication

Trigger: User presents PIV card to authenticate.
Actors: End User (with PIV card), Client Agent, MFA Server

Steps:

1. piv_pre_auth → server generates nonce, creates PivAuthSession
2. Client signs nonce with PIV card → piv_auth
3. Server finds DevicePivCertificate by cert hash, validates chain + revocation
4. Verifies signature matches stored public key
5. Auth success → audit logged

API Endpoints: piv_pre_auth, piv_auth

4.3 — PIV Header-Based Authentication (mTLS)

Trigger: TLS termination proxy passes client certificate in HTTP header.
Actors: TLS Proxy, Client with PIV card, MFA Server

Steps:

1. Client establishes mTLS connection with TLS proxy
2. Proxy extracts client certificate → passes in X-Client-Cert header
3. piv_header_auth → server parses certificate from header
4. Looks up DevicePivCertificate by hash
5. Validates chain, revocation, and certificate status
6. Auth success → session created

API Endpoints: piv_header_auth

Notes: This is a single API call but the TLS handshake with the proxy is the multi-step process.

5. PIV IoT Device Authorization Workflows

5.1 — IoT Device Registration

Trigger: Admin or API registers a new IoT device (drone, sensor, access point) in the system.
Actors: Admin or External System, MFA Server

Steps:

1. piv_iot_register_device → creates PivIotDevice record with:
   • DeviceKey (unique identifier)
   • DeviceName, DeviceType, Location
   • AllowedActions (what this device can authorize)
   • RequiredKeySlots (which PIV key slots are accepted)
   • mTLS config: RequireMutualTls, DeviceCertificate
   • Cellular config: IsCellularDevice, Imei, Iccid
   • Offline config: OfflineAuthEnabled, MaxOfflineDuration
2. Optionally creates a corresponding Device record (Type = 16, PivIotDevice) for token management

API Endpoints: piv_iot_register_device

5.2 — IoT Device Authorization

Trigger: An IoT device needs to verify that a user with a PIV card is authorized to operate it.
Actors: IoT Device, User with PIV card, MFA Server

Steps:

1. User presents PIV card to IoT device reader
2. IoT device calls piv_iot_authorize with device key + certificate data
3. Server validates:
   • Device is registered and enabled (PivIotDevice)
   • Certificate is valid (chain, revocation)
   • User is authorized for this device's AllowedActions
   • Geofence check (if configured)
4. Creates PivAuthSession → returns authorized actions
5. IoT device grants access for session duration

API Endpoints: piv_iot_authorize, piviotauthorize_cellular (for cellular devices)

5.3 — IoT Offline Auth Bundle & Sync

Trigger: IoT device needs to operate in an area without network connectivity.
Actors: MFA Server, IoT Device

Steps:

1. Pre-flight (online): System issues PivIotOfflineAuthBundle containing:
   • List of authorized users/certs (hashed)
   • Geofence boundaries (MaxFlightRadius, MaxAltitude, GeofenceData)
   • Validity window (ValidFrom / ValidUntil)
   • Signed hash for tamper detection
2. Offline operation: IoT device validates PIV certs locally against the bundle
3. Reconnection: Device calls piviot_offline_sync → uploads PivIotOfflineEvent records
4. Server validates each event against the bundle hash → marks Validated = true/false
5. Events with invalid bundle hashes are flagged for admin review

API Endpoints: piviot_offline_sync

Data Flow:

• Creates: PivIotOfflineAuthBundle (pre-flight), PivIotOfflineEvent (sync)
• Updates: PivIotDevice (LastConnectedDate, battery level, signal strength, coordinates)

6. Session Management Workflows

6.1 — Session Token Lifecycle

Trigger: Successful authentication; client needs a persistent session.
Actors: Client Application, MFA Server

Steps:

1. After auth success → create_session_token → server generates token, stores with expiration
2. Client stores session token (cookie, header, or local storage)
3. Subsequent requests include token → is_session_token_valid → server validates
4. On logout or timeout → expire_session_token → token invalidated

API Endpoints: create_session_token, is_session_token_valid, expire_session_token

7. SSO/SAML Workflows

7.1 — SAML2 SSO Login

Trigger: User accesses a Service Provider (SP) application that redirects to SurePassID as the Identity Provider (IdP).
Actors: End User, Service Provider, SurePassID IdP, Browser

Steps:

1. User accesses SP application (e.g., Salesforce, AWS Console)
2. SP generates SAML AuthnRequest → redirects browser to SurePassID IdP SSO URL
3. SurePassID displays login page → user authenticates (any Workflow 1.x method)
4. IdP generates SAML Response with signed Assertion containing:
   • NameID (user identifier)
   • Attributes (email, groups, roles) configured in PartnerSSOApps
   • Session index
5. Browser POSTs SAML Response to SP ACS URL
6. SP validates signature using IdP certificate from PartnerSSOSettings
7. SP creates local session → user logged in

Data Flow:

• Reads: PartnerSSOApps (SP configuration), PartnerSSOSettings (signing cert), PartnerUserSSOActivation (SSO session)
• Writes: PartnerUserSSOActivation (SSO session record), PartnerUserAudit

7.2 — SAML2 Single Logout (SLO)

Trigger: User logs out from one SP or the IdP, triggering logout across all active sessions.
Actors: End User, Initiating SP, SurePassID IdP, Other SPs, Browser

Steps:

1. User clicks logout at SP (or IdP)
2. SP sends LogoutRequest to SurePassID IdP
3. IdP validates LogoutRequest signature (if SSO Require Signed Logout Requests = true)
4. IdP looks up all active SSO sessions for this user (PartnerUserSSOActivation)
5. For each other SP with an active session:
   • IdP sends LogoutRequest (binding per SSO SP Logout Binding: HTTP-POST or HTTP-Redirect)
   • Waits for LogoutResponse from each SP
6. IdP invalidates local session
7. IdP sends LogoutResponse to initiating SP (signed if SSO Sign Logout Responses = true)
8. User logged out of all applications

Data Flow:

• Reads/Deletes: PartnerUserSSOActivation (all sessions for user)
• Reads: PartnerSSOApps (logout URLs, binding config)

8. Token Ordering & Inventory Workflows

8.1 — Manual Hardware Token Order

Trigger: Admin places an order for hardware security keys (e.g., YubiKeys) through the admin portal.
Actors: Admin, Admin Portal, MFA Server, YubiEnterprise Delivery API

Steps:

1. Admin navigates to tokenorderdetail.aspx
2. Selects product (e.g., YubiKey 5 NFC), quantity, shipping address
3. Clicks "Submit Order" → TokenOrder created (status: PendingApproval)
4. Admin (or approver) reviews and approves → status: Approved
5. System calls YubiEnterprise Delivery API to create shipment
6. Yubico ships keys → tracking number received → status: Shipped
7. Keys delivered → status: Delivered
8. Yubico webhook calls token_order_register with serial numbers
9. TokenInventory records created (status: Available)

Data Flow:

• Creates: TokenOrder, TokenInventory
• Updates: TokenOrder (status transitions, tracking, timestamps)
• Reads: PartnerSettings (YubiEnterprise API token, default shipping address)

8.2 — FIDO2 Pre-Registration Order

Trigger: Admin orders YubiKeys with FIDO2 credentials pre-registered for specific users.
Actors: Admin, MFA Server, YubiEnterprise API

Steps:

1. Admin creates order with OrderType = Fido2PreReg and assigns to user
2. System generates ECC key pair (YubiFprEncryptionService)
3. Submits to YubiEnterprise API with FidoPinRequest + FidoCredentialRequests
4. YubiKey ships with credentials pre-loaded
5. On delivery, YubiEnterprise returns encrypted FPR response
6. System decrypts PIN and credential data using stored private keys
7. Registers credentials in DeviceFIDOApp → user can authenticate immediately

Data Flow:

• Creates: TokenOrder (with FprPrivateKeys, FprResponseData), DeviceFIDOApp
• Reads: PartnerSettings.YubiEnterpriseFido2CustomizationId, YubiEnterpriseFido2PinLength

8.3 — Token Inventory Management

Trigger: Admin manages physical token stock — assigning, unassigning, and retiring tokens.
Actors: Admin, MFA Server

Steps:

1. Tokens received → TokenInventory status = Available
2. Admin assigns to user → token_inventory_assign → status = Assigned, AssignedUserId set
3. If token also needs MFA registration: admin creates Device record, links to TokenInventory.AssignedDeviceId
4. User departs or token replaced → token_inventory_unassign → status = Available
5. Token damaged or expired → admin retires → status = Retired, RetiredDate set

API Endpoints: token_inventory_find, token_inventory_assign, token_inventory_unassign

9. Admin & Operations Workflows

9.1 — Tenant Onboarding

Trigger: System admin creates a new tenant (Partner) in SurePassID.
Actors: System Admin, MFA Server

Steps:

1. System admin creates new Partner record
2. System creates PartnerSettings with default values
3. usp_CreateDefaultTemplatesForPartner copies all system notification templates to the new tenant
4. First admin user created for the tenant
5. TenantWelcome email sent to admin with login credentials, setup instructions, and Authenticator QR code
6. Admin logs in → configures MFA policies, FIDO2 settings, SAML apps, etc.

9.2 — Tenant Configuration

Trigger: Admin modifies tenant-level settings in clientsettings.aspx.
Actors: Admin, Admin Portal

Steps:

1. Admin opens Settings page → UI loads current values from PartnerSettings
2. Admin modifies settings (FIDO2 config, PIN policy, push settings, log settings, etc.)
3. Clicks Save → PartnerSettings updated → ModifiedDate + ModifiedByPartnerUserId stamped
4. Changes take effect immediately for all subsequent auth requests

Settings Categories:

• FIDO2 (passwordless, second factor, supported releases, admin activate)
• PIN Management (VPN PIN reset, alpha PINs, PIN length)
• Push/IVR (push timeouts, IVR cancel key, IVR timeout)
• System Log (audit record count, log controls)
• Token Management (mobile resets, token expiration, drift units, provisioning issuer)
• User Authentication (login by email, login by SSO name)
• Failed Login Policy (max failed attempts)

9.3 — Event Log Sync (Multi-Site)

Trigger: Remote SurePassID server synchronizes its audit records with a central server.
Actors: Remote MFA Server, Central MFA Server

Steps:

1. Remote server calls event_log_sync_start on central server
2. Central server returns audit records where RemoteSyncDate is NULL (not yet synced)
3. Remote server stores records locally
4. Central server updates RemoteSyncDate on synced records

API Endpoints: event_log_sync_start

9.4 — Notification Template Customization

Trigger: Admin customizes notification templates for their tenant.
Actors: Admin, Admin Portal

Steps:

1. Admin navigates to notification template management
2. Views tenant-specific templates (initially copied from system defaults)
3. Edits template body, subject, from address using {{placeholder}} syntax
4. Saves → NotificationTemplate record updated → Version incremented
5. Future notifications for this tenant use the customized template
6. System resolves templates in order: Partner-specific → System default

Partial List of Available Placeholders:

• {{user.fullName}}, {{user.loginName}}, {{user.email}}, {{user.cellPhone}}
• {{tenant.name}}, {{tenant.domain}}
• {{otp}}, {{otp.expirationMinutes}}
• {{token.serialNumber}}, {{token.activationUrl}}, {{token.qrCodeImage}}
• {{password}}, {{loginUrl}}, {{resetUrl}}
• {{currentDate}}, {{currentTime}}, {{ipAddress}}

9.5 — API Key Management

Trigger: Admin creates or manages API keys for external system integration.
Actors: Admin, Admin Portal

Steps:

1. Admin navigates to API Keys page
2. Creates new API key with:
   • Description
   • Access Login (username)
   • Access Key (password/secret)
   • Access Rights (semicolon-separated ApiPermission IDs)
3. PartnerApi record created
4. External systems use this API key to authenticate REST API calls
5. Each API call is authorized against ApiPermission + ApiEndpoint tables
6. Admin can revoke or modify permissions at any time

Data Flow:

• Creates/Updates: PartnerApi
• Reads (on each API call): PartnerApi, ApiPermission, ApiEndpoint

10. Notification Workflows

10.1 — Unified Notification Delivery

Trigger: Any system event that requires user or admin notification.
Actors: MFA Server, Notification Service, SMTP Server, Twilio (SMS/Voice), APNs/FCM (Push)

Steps:

1. System event occurs (OTP request, device activation, password reset, account locked, etc.)
2. Notification service resolves template:
   • Look for partner-specific template (NotificationTemplate where PartnerId = tenant)
   • Fall back to system default (PartnerId = NULL)
3. Substitute placeholders ({{user.fullName}}, {{otp}}, etc.)
4. Route to delivery channel based on NotificationType:
   • 1 = Email → SMTP server (from address, subject, HTML or plaintext body)
   • 2 = SMS → Twilio API (short format, character limits)
   • 3 = Voice/IVR → Twilio voice API (text-to-speech)
   • 4 = Push → APNs (iOS) or FCM (Android) via push token
5. Audit logged to PartnerUserAudit (SendEmail=68, SendSms=69, SendVoice=70)

Template Codes (complete list):

11. Planned: Risk-Based Authentication

11.1 — Risk-Based Adaptive Authentication

Status: Planned — Ovreview Trigger: Any authentication attempt when RBA is enabled for the tenant.
Actors: End User, Client Application, MFA Server, GeoIP Service, Risk Scoring Engine

Steps:

1. Primary authentication succeeds (any Workflow 1.x)
2. RiskAuthenticationHandler collects contextual signals:
   • IP address → GeoIP lookup (country, city, lat/long)
   • User-Agent → device fingerprint hash
   • Timestamp → off-hours check
3. RiskScoringService evaluates 9 risk factors against user's PartnerUserRiskProfile
4. Computes composite score (0–100)
5. Compares to tenant thresholds:
   • Score < 30 → Allow (log score, update profile)
   • 30 ≤ Score < 90 → Step-Up (create RiskStepUpSession, trigger additional factor)
   • Score ≥ 90 → Block (deny access, alert admin)
6. Score + factors written to PartnerUserAudit
7. User's PartnerUserRiskProfile incrementally updated after low-risk success

Workflow Summary

Total: 38 workflows spanning ~60+ API endpoints, multiple UI pages, background processes, and external service integrations.