Customer Onboarding & SSO Integration

Overview

APEX provides a configurable customer onboarding process integrated with Azure AD B2C for authentication. You can implement and customize the onboarding flow for your tenant using the schemas and configurations detailed in this guide.

Azure AD B2C SSO Integration

APEX uses Azure AD B2C as its identity provider for customer authentication. You must define the B2C configuration in the tenant configuration schema:

"B2CConfiguration": {
  "authority": "https://login.lightstone.co.za/tfp/lsgb2c.onmicrosoft.com/B2C_1A_SIGNUPORSIGNINV2_TEST/",
  "passwordReset": "https://login.lightstone.co.za/tfp/lsgb2c.onmicrosoft.com/B2C_1A_PASSWORDRESETV2_TEST/",
  "clientId": "your-application-specific-client-id",
  "scopes": ["openid", "profile"],
  "knownAuthorities": ["lsgb2c.b2clogin.com", "login.lightstone.co.za"]
}

For detailed information on SSO configuration and implementation, please refer to the SSO Integration Guide.

Onboarding Flow Configuration

The onboarding process consists of configurable steps that collect user information according to defined schemas. You control the configuration through two primary schemas:

1. Tenant Configuration Schema (tenantconfig.schema.json): Defines the steps, forms, and flow of the onboarding process
2. Onboarding Schema (onboarding.schema.json): Defines the data structure for user and company information

Tenant Configuration

The tenant configuration schema allows you to define:

• Steps: Ordered sequence of forms presented to users during onboarding
• Navigation: Title and hero elements for the onboarding UI
• Routing: Landing URLs for new and returning users
• B2C Configuration: Authentication settings

Step Configuration

Define each step in the onboarding process with:

{
  "order": 1,
  "title": "Personal Information",
  "description": "Please provide your personal details",
  "form": {
    "type": "VerticalLayout",
    "elements": [
      // Form layout elements
    ]
  },
  "webhook": {
    // Optional webhook configuration
  },
  "notification": {
    // Optional notification configuration
  }
}

Form Elements and Layout

Construct forms using nested elements:

{
  "type": "VerticalLayout",
  "elements": [
    {
      "type": "Control",
      "scope": "#/properties/contact/properties/name",
      "label": "First Name"
    }
  ]
}

Conditional Rules

Apply conditional logic to show/hide fields:

"rule": {
  "effect": "SHOW",
  "condition": {
    "scope": "#/properties/userType",
    "schema": "company"
  }
}

Webhooks and Notifications

Configure webhooks to integrate with external systems:

"webhook": {
  "url": "https://api.example.com/webhook",
  "headers": [
    {
      "key": "Content-Type",
      "value": "application/json"
    }
  ],
  "body": {
    "transformations": [
      {
        "order": 0,
        "jsonata": {
          "expression": "{ \"userData\": $ }"
        }
      }
    ]
  }
}

Configure notifications to send emails or WhatsApp messages:

"notification": {
  "email": {
    "to": ["{{user.emailAddress}}"],
    "subject": "Welcome to APEX",
    "template": "welcome-template"
  }
}

Onboarding Data Structure

The onboarding schema (onboarding.schema.json) defines the data structure collected during the onboarding process.

User Types

APEX supports two user types:

• individual: For personal accounts
• company: For business accounts

Contact Information

The Contact object stores personal information:

{
  "name": "John",
  "surname": "Doe",
  "title": "Mr",
  "emailAddress": "john.doe@example.com",
  "cellphoneNumber": "+27123456789",
  "profession": "Professional"
  // Additional fields...
}

Company Information

The Company object stores business information:

{
  "registeredName": "Acme Inc.",
  "registrationNumber": "2021/123456/07",
  "tradingName": "Acme",
  "entityType": "privateCompany",
  "vatNumber": "4123456789",
  "vatRegistered": true
  // Additional fields...
}

Address Structure

Both individuals and companies can have physical and postal addresses:

"addresses": {
  "physical": {
    "line1": "123 Main Street",
    "city": "Johannesburg",
    "postalCode": "2000",
    "country": "South Africa",
    "province": "Gauteng"
  },
  "postal": {
    // Postal address fields
  }
}

Document Management

The schema supports various document types for verification:

"documents": {
  "IDDocument": {
    "files": [
      {
        "name": "id-document.pdf",
        "size": 1024000,
        "url": "https://storage.example.com/documents/id-document.pdf"
      }
    ]
  }
}

Implementation Examples

Complete Tenant Configuration Example

{
  "steps": [
    {
      "order": 1,
      "title": "Account Type",
      "description": "Select your account type",
      "form": {
        "type": "VerticalLayout",
        "elements": [
          {
            "type": "Control",
            "scope": "#/properties/userType",
            "label": "Account Type"
          }
        ]
      }
    },
    {
      "order": 2,
      "title": "Personal Information",
      "description": "Enter your personal details",
      "form": {
        "type": "VerticalLayout",
        "elements": [
          {
            "type": "Control",
            "scope": "#/properties/contact/properties/name",
            "label": "First Name"
          },
          {
            "type": "Control",
            "scope": "#/properties/contact/properties/surname",
            "label": "Last Name"
          }
        ]
      },
      "rule": {
        "effect": "SHOW",
        "condition": {
          "scope": "#/properties/userType",
          "schema": "individual"
        }
      }
    }
  ],
  "nav": {
    "title": "APEX Onboarding",
    "hero": "Welcome to APEX"
  },
  "routing": {
    "landingUrls": {
      "new": "/onboarding/welcome",
      "returning": "/onboarding/continue"
    }
  },
  "B2CConfiguration": {
    "authority": "https://apexb2c.b2clogin.com/apexb2c.onmicrosoft.com/B2C_1_signin",
    "passwordReset": "https://apexb2c.b2clogin.com/apexb2c.onmicrosoft.com/B2C_1_reset",
    "clientId": "00000000-0000-0000-0000-000000000000",
    "redirectUrl": "https://app.apex.com/auth",
    "logoutRedirectUrl": "https://app.apex.com/logout",
    "scopes": ["https://apexb2c.onmicrosoft.com/api/user.read"],
    "knownAuthorities": ["apexb2c.b2clogin.com"]
  }
}

Best Practices

1. Schema Validation: Always validate your tenant configuration against the schema before deployment
2. Step Order: Ensure step orders are sequential and don't contain gaps
3. Conditional Logic: Test all conditional rules to ensure they behave as expected
4. B2C Policies: Configure appropriate user flows in Azure AD B2C to match your onboarding requirements
5. Error Handling: Implement proper error handling for API responses and form validation

Reference

• Azure AD B2C Documentation
• JSON Schema Specification