> ## Documentation Index > Fetch the complete documentation index at: https://docs.ulm.m1amdocs.com/llms.txt > Use this file to discover all available pages before exploring further. # Onboard and Authenticate Process This multi-step process combines onboarding, authentication, account association, and handles a user's subscription purchases all in one seamless flow. The **Onboard and Authenticate** Process allows your organization to manage new and existing users that may have current subscriptions or are about to make a purchase. Digital Identity Management verifies their identity, provides multiple secure methods for login/sign-in, and can auto-discover active subscriptions associated with the user's account. There are many paths a user can take that depends on their user status, security implementation, and type of UI flow such as onboarding or login. These enhanced processes allow integration with external B/OSS systems for subscription and account management. If no integration is required, the user processed as a regular ULM user. To accommodate all the different flows, two main processes execute to initiate and complete a user's journey: * The first or initial **Onboard and Authenticate** Process handles user onboarding, authentication, and account association for existing users. All existing users with a verified AuthN ID start and finish with this flow that supports MFA, FIDO2, and One-Time Password (OTP). * New users (users that don't exist yet) start with the initial **Onboard and Authenticate** flow and continue with the **Onboard, Authenticate, and Activate** Process (also known as the **Finish Login and Enroll** Process). This second process completes the creation, activation and verification of a User ID in the Digital Identity Management system. Optionally, the new user may be required to set their password or register factors for MFA. Once the password is updated in the Digital Identity Management Data store, the authentication identifier (authN ID) is processed, and the current user is verified in the Digital Identity Management environment. * Additionally, this second **Onboard, Authenticate and Activate** Process may be invoked when a user logs in with an authN ID and OTP/Magic Link. This Process enhances and extends Digital Identity Management's standard onboarding, authentication, or account/subscription Processes in one dynamic flow. **Onboard and Authenticate** is a very flexible multi-part process that supports all types of users, partner integration(s), and a variety of other configuration points including: **Login options** Many of these options are controlled through [App Settings](#section_t4k_m2t_cpb) and enable users the ability to login with or without a password. Additionally, Digital Identity Management supports FIDO2, OTP, and magic links as valid sign-in/login options. Some of the relevant [App Settings](#section_t4k_m2t_cpb) for login are: | Application Settings | Sample Value | | | | - | - | - | - | | `showLoginPrompt` | Prompt displayed to user to select login option such as a password, OTP, Magic Link, or FIDO2. | True \\ | False | | `notifyUser` | Determines if user receives notification from the current process. | True \\ | False | | `passwordLifeTimeSeconds` | Defines the expiration period in seconds for the password. | 0**Note:** If this value is set to 0, the password never expires. | | | `maxInputAttempts` | Number of times user can enter an invalid password. | 3 | | | `passwordComplexityRules` | Defines a valid password format and length that a user can submit to process. Refer to the Admin Guide's **Password Complexity Rules** for more details. | The password data, as defined by the password settings, is stored in a json format. | | | **reCAPTCHA (Optional)** | | | | The Process supports reCAPTCHA Invisible Badge (v2, v3, enterprise) on the first prompt for user onboarding and authentication. Some of the relevant [App Settings](#section_t4k_m2t_cpb) for this feature are: | Application Settings | Sample Value | | | - | - | - | | `promptCaptcha` | Defines if the recaptcha prompt is enabled or disabled. | False | | `recaptchaSecret` | The shared key between the platform and reCAPTCHA. | \ | | `recaptchaSite` | The site key to use for the client-side integration. | [www.google.com](http://www.google.com) | **Multi-factor Authentication (MFA)** The user is prompted to enter or register a second factor. Some of the relevant [App Settings](#section_t4k_m2t_cpb) for this feature are: | Application Settings | Sample Value | | | - | - | - | | `promptMFAOnSetPassword` | This setting determines if the user needs to complete second factor verification when submitting their password for the first time. | 0 | | `minMfaCount` | Determines if MFA is used and sets the minimum number of MFA factors required for the user profile. | 2 | | `verificationRequired` | During registration of the 2FA method user prompted to validate selected channel. | true | | `2FAMaxRetryVerification` | Defines the maximum retries for the 2FA verification step. | 5 | **Subscription and Account Management** Digital Identity Management supports integration with external B/OSS platforms and retrieves subscription data, payment methods, purchases, and associates accounts with a valid user. Some of the relevant [App Settings](#section_t4k_m2t_cpb) for this feature are: | Application Settings | Sample Value | | | - | - | - | | `accountDiscovery` | This setting determines if the user needs to complete second factor verification when submitting their password for the first time. | 0 | | `discoverAccountsby` | A list of supported types of mechanisms for account discovery such email or mobile.. | true | | `enforce-account-association` | Performs an account association to the User ID if no PLM code is returned. This setting is contained within the `clientConfiguration` json. | true | ## Onboard and Authenticate Process Flow The Digital Identity Management Identity App supports several configurable flows out of the box and provides dynamic pages to guide the user through their journey. Your organization's configuration uses [App Settings](#section_t4k_m2t_cpb) and user inputs to determine which UI pages are rendered and what processes are called throughout the user journey. \[product: dim]Onboard and authenticate process flow\[/product: dim] This section describes the Authenticate Process from a high-level, "happy path" flow. **Preconditions** * The user has a password. * The User ID exists in Digital Identity Management. **Basic Flow** 1. Digital Identity Management queries the external billing support or operations system (B/OSS) to retrieve a product code (PLM Code). The PLM Code returns metadata that contains the Product Id, purchase URL, and terms of service. **Note:** The user is processed as a regular ULM user if no PLM code is returned. 2. The user navigates to the application's login/sign-in page and selects their identifier to use such as their email address or mobile number. 3. **reCAPTCHA** (Conditional) If the client integrated a reCAPTCHA service, then Google checks the user's input and if successful, returns a validation token to the client. 4. Digital Identity Management consumes and submits the identifier using the [PUT /process/step](c_processStep) to retrieve the user's account information. 5. The **Validate Account** process returns the account and relevant information such as the payment method(s) and eligibility data for the specified user. **Note:** If the user logs in with no password or the User ID doesn't exist, the current Process exits and invokes the secondary **Onboard, Authenticate, and Activate** Process. Digital Identity Management generates and sends the user a notification message that contains [Access token](c_actionTokens#) as a short custom One-time Passcode (OTP) for the next step. 6. The user enters their password for validation. Depending on your [App Settings](#section_t4k_m2t_cpb), the following may apply: * **FIDO2** (Conditional) is configured, the user is redirected to another page (UI) to enter their credentials and the current process resumes. * **MFA** (Conditional) is configured, the user selects the MFA type from a supplied list of previously registered factors. If the user doesn't have any registered factors, they're directed to setup MFA before continuing. This option is controlled by the [App Setting](#section_t4k_m2t_cpb) **minMfaCount**. * **Password** (Conditional) is expired, and the user is prompted to enter a new password. This option is controlled by the [App Setting](#section_t4k_m2t_cpb) **passwordLifeTimeSeconds**. **Note:** If the user chooses to enter an OTP or Magic Link, the current Process exits and invokes the secondary **Onboard, Authenticate, and Activate** Process to complete authentication. 7. Digital Identity Management updates the payment methods and invokes `GET submgnt/v2/subscriptions` API to retrieve the subscriptions to associate with the specified account and performs an entitlement check. **Note:** If no PLM code is available, the current Process prompts a regular ULM user for the account id to complete the account association using the [Associate Account to User](c_associateBillingAccountV2) Process. **Post-conditions** * The existing user is successfully logged in and has access to services according to their subscription and entitlements. * The user receives a purchase prompt on their UI (if required). **Possible or Common Errors** * The product code (PLM) is invalid. * The provided mobile number or email is already registered to an existing Digital Identity Management User. * The mobile number or email doesn't pass validation rules. * The provided password does not match the password complexity settings. * The user selects an unsupported MFA method. * The user enters an invalid OTP/TOTP that may be caused by incorrect digits, expired code, or wrong pkat. * The user doesn't have any associated accounts or payment methods set up and therefore isn't eligible to use the requested service. ## Response Parameters Depending on where the user is on their journey, the **Onboard and Authenticate** Process records events and returns these properties as required: | Name | Trigger | CustomPayload | Admin UI | Description | | - | - | - | - | - | | PROCESS\_START | Process initiation. | `relayingPartyId` (if available) | `uiFlowType: LOGIN` | User selected to authenticate into the service. | | `uiFlowType: ONBOARD` | User selected to onboard into the service. | | | | | `uiFlowType: COMBINED` | User selected to either onboard or authenticate into the service. | | | | | PROCESS\_END | Process ends normally. | `userId` (if created) `identifier` | `**uiFlowType**: LOGIN` **Result**: User is signed in with password. | Successfully authenticated with \{identifier\}. | | `**uiFlowType:** LOGIN` **Result**: not signed in, OTP sent to the user. | Verification code was sent to \{identifier\}. User must provide code to sign in. | | | | | `**uiFlowType:** ONBOARD` **Result**: The user is not activated, OTP sent to user. | Verification code was sent to \{identifier\}. User must provide code to complete onboarding. | | | | | `**uiFlowType:** COMBINED` **Result**:The user is signed in (no OTP) | Successfully authenticated with \{identifier\}. | | | | | `**uiFlowType:** COMBINED` **Result**: Neither flow has signed in or onboarded, OTP sent to user. | Verification code was sent to \{identifier\}and the user must provide this code to complete their onboarding or sign-in attempt. | | | | | PROCESS\_TIMEOUT | After the process times out. | `userId` (if created) identifier | | | | GET\_PROD\_INFO\_SUCCESS | After successfully get product information from PLM. | `productId` `produceName` | | Retrieved product information for for \{productName\} (\{productId\}). | | VALIDATE\_ACCOUNT\_SUCCESS | After the process successfully validates account. | `identifier` | | Successfully validated account for \{identifier\}. | | PROCESS\_SEND\_VERIFICATION | After request for verification sent to destination. | `identifier` | | Request for verification sent to \{identifier\}. | | USER\_AUTHENTICATED | After user is successfully authenticated. | | | User successfully authenticated. | | GET\_SUBSCRIPTIONS\_SUCCESS | After user has successfully retrieved subscription information. | | | Successfully get subscriptions for account \{accountId\}. | ## Onboard, Authenticate and Activate Process Flow Digital Identity Management provides user onboarding, authentication and activation using the **Onboard, Authenticate and Activate** Process. A new user navigates to a login page to sign themselves up by providing an AuthN ID (mobile/email), password, and registration details. Once the user is activated and authenticated, they can log in to access the service(s), and/or make a subscription purchase. This process is also used for existing users that sign in with an OTP or Magic Link. The user already has a verified authN ID in Digital Identity Management. This second process is different from the **Onboard and Authenticate** Process because it starts with the `GET session/token` Process. The current user has an access token from the first Process to complete their onboarding and authentication journey. This section describes the **Onboard, Authenticate and Activate** Process from a high-level, "happy path" flow. \[product: dim]Onboard, authenticate and activate user process flow\[/product: dim] **Preconditions** * The User ID doesn't exist in Digital Identity Management. * The user has no password. * The user has an access token. **Basic Flow** 1. The user navigates to your application's sign-in page, and submits the OTP they received from the initial **Onboard and Authenticate** Process. 2. Digital Identity Management updates the payment methods and invokes `GET submgnt/v2/subscriptions` API to retrieve the subscriptions to associate with the specified account and performs an entitlement check. **Note:** If no PLM code is available, the current Process completes the account association using the [Associate Account to User](c_associateBillingAccountV2) Process. 3. Digital Identity Management prompts the user for a password and additional information that includes: **First Name**, **Last Name**, **Display Name**, and **Language**. The process sets the password and other attributes using the `PUT /process/step` API. 4. Digital Identity Management creates the User entity and activates the authentication identifier (AuthN ID). 5. **Note:** If MFA is enabled and/or needs to be configured, Digital Identity Management sends a corresponding [pkat](c_actionTokens#)[Digital Identity Management Action Token](c_actionTokens#) to your client application. The client application retains this information for onboarding flows where the user needs to enter their OTP. 6. If no PLM code is available, the current Process prompts a regular ULM user for the account id to complete the account association using the [Associate Account to User](c_associateBillingAccountV2) Process. 7. The user receives a purchase prompt on their UI (if required). **Post-conditions** * A new User entity exists in Digital Identity Management with a verified AuthN ID (mobile/email). * The new user's password is created/updated. * The new user is successfully logged on. **Possible or Common Errors** * The provided password does not match complexity settings. * The mobile/email does not pass validation rules. * The client submitted a request with a missing expected input parameter (e.g., no email or mobile provided). * The user selects an unsupported MFA method. * The user enters an invalid OTP/TOTP that may be caused by incorrect digits, expired code, or wrong pkat. * The user doesn't have any associated accounts or payment methods set up and therefore isn't eligible to use the requested service. The **Onboard, Authenticate and Activate** Process supports additional configuration points within this flow such as: * **Password Option** – In the onboarding or authentication flows, this Process creates a new password for a new user or updates a password if the user doesn't have one and is required to set one. Several password options are controlled through the App Settings. * **Collect User Data** – Your client application prompts for additional information such as the user's First Name, Last Name, Display Name, and Preferred Language in the onboarding flow. * **Subscription and Account Management** – Digital Identity Management supports integration with external B/OSS platforms and retrieves subscription data, payment methods, purchases, and associates accounts with a valid user. If the user doesn't have any active subscriptions, a purchase prompt can be enabled to guide the user through a subscription purchase. ## Response Parameters Depending on where the user is on their journey, the **Onboard, Authenticate and Activate** Process records events and returns these properties: | Name | Trigger | Custom Payload | Admin UI | Description | | - | - | - | - | - | | PROCESS\_START | Process initiation | | | The Onboard, Authenticate, and Activate process started. | | PROCESS\_END | Process ends normally | `userId identifier` (if created) | `**uiFlowType**: LOGIN` | Successfully authenticated with \{identifier\}. | | `**uiFlowType:** ONBOARD` | Successfully onboarded and activated with \{identifier\}. | | | | | `**uiFlowType:** COMBINED` The user exists without a password. | Successfully authenticated with \{identifier\}. | | | | | `**uiFlowType:** COMBINED` The user doesn't exist. | Successfully onboarded and activated with \{identifier\}. | | | | | PROCESS\_TIMEOUT | After the process times out. | `userId identifier` (if created) | | | | GET\_PROD\_INFO\_SUCCESS | After successfully get product information from PLM. | `productId` `produceName` | | Retrieved product information for for \{productName\} (\{productId\}. | | VALIDATE\_ACCOUNT\_SUCCESS | After successfully validate account. | `identifier` | | Successfully validated account for \{identifier\}. | | PROCESS\_SEND\_VERIFICATION | After request for verification, a notification is sent to specified destination (email/mobile). | `identifier` | | Request for verification sent to \{identifier\}. | | USER\_AUTHENTICATED | After user is successfully authenticated. | | | User successfully authenticated. | | GET\_SUBSCRIPTIONS\_SUCCESS | After user has successfully get subscription information. | | | Successfully get subscriptions for account \{accountId\}. | ## Application Settings Certain aspects of the Process' behavior are controlled by configurable [App Settings](#section_t4k_m2t_cpb). | Application Settings | Sample Value | | | | - | - | - | - | | `withAccountDiscovery` | The process performs account discovery and creates the ASF associations for the specific user. | true | | | `discoverAccountsBy` | A list of supported types of mechanisms such email or mobile that can be used for account discovery. | mobile | | | `clientConfiguration` | A JSON client configuration with specific client information used to set the process and default system flags. | The supported options and defaults are: - enforce-account-association (false) - enforce-product (false) OIDC client specific example`{ "cliendId1": { "enforce-account-association": true "enforce-product": true } }` | | | `promptMFAOnSetPassword` | This setting determines if the user needs to complete second factor verification when submitting their password for the first time. | 0 | | | `passwordComplexityRules` | Defines the criteria for a valid password when the user is onboarding, or resetting/updating their password. Configuration points include:- **Upper case characters** - The password requires at least one uppercase (A-Z) character. - **Lower case characters**The password requires at least one lowercase (a-z) character. - **Special characters**The password requires at least one [special character](reusePasswordSettingSpecialCharsList). - The password requires at least one numeric (0-9) character. - The minimum password length. | - A-Z: Enabled - a-z: Enabled - (!"#\$%&'()\*+,-./:;=>?@\[\\]^\_\`\{\\ | \}\~): Enabled - 0-9: Enabled - Minimum length: 8 | | `passwordDictionary` | The submitted password is verified against this comma separated list of prohibited passwords. | Static list provided by Digital Identity Management | | | `maxInputAttempts` | The number of times a user can enter an invalid password before their account is locked. | 3 | | | `longTokenExpirationPeriodinMinutes` | Determines the number of minutes before a verification link expires. | 28800 minutes (20 days) | | | `shortTokenExpirationPeriodinMinutes` | Determines the number of minutes before an OTP expires. **This setting is not configurable; it is noted here for context**. | 5 minutes | | | `emailObfuscationGroupingPattern` | Defines the logic for an acceptable email format in JSON format. This pattern is used to parse email address for obfuscation rule. | `.+@.+\..+` | | | `emailObfuscationRule` | Email obfuscation rule to be used to encrypt or decrypt an email. | $1\*\*\*\*$3 | | | `phoneObfuscationGroupingPattern` | Defines the logic for an acceptable mobile number format. The data is in JSON format. This pattern is used to parse phone number for obfuscation rule. | `^(?:[0-9] ?){6,14}[0-9]$` | | | `phoneObfuscationRule` | Phone obfuscation rule to be used to encrypt or decrypt an phone number. | \*\*\*-\*\*\*-\*\*\$1 | | | `2FAMaxRetryVerification` | Defines the maximum retries for the 2FA verification step. | 5 | | | `passwordLifeTimeSeconds` | Expiration period in seconds for the password. It this setting equals 0, the user's password never expires. | 0 | | | `passwordHistoricalCheckingCount` | Defines the threshold (in seconds) to prohibit reuse of password up to a previous date. | 0 | | | `passwordHistoricalCheckingPeriodSeconds` | Defines the threshold (in seconds) to prohibit the reuse of the password used from a date onwards. If this value is equals 0 then, no check occurs. | 0 | | | `emailDomainBlacklist` | Comma-separated list of prohibited email domains. | null | | | `minMfaCount` | Minimum number of MFA factors required for the user profile. | 2**Note:** If this value is 0, then MFA is disabled and no factors are required. | | | `verificationRequired` | During registration of the 2FA method user prompted to validate selected channel. | true | | | `createOTTAccount` | Determines if an OTT account is to be created for the user. | false | | | `OTTPaymentMethodType` | The default payment method for the the specified OTT account. | map | | | `notifyUser` | Determines if the user receives a notification. | true | | | `notifyUserOnboarded` | Determines if the user receives notification about a successful onboarding. | false | | | `showLoginPrompt` | The login prompt is shown to the user who selects their desired option which can be password, OTP, MagicLink, or FIDO2. | false | | | Your organization can manage these and other settings in the MarketONE Admin console or during your setup of your Digital Identity Management instance or tenant. During your integration and testing cycles, be aware that debug mode can be enabled in STG and PDT environments only (not in Production). | | | | Debug mode allows UI developers and QA to get some extra information about the REST calls and the relevant response/data. For example we may return user otp that is sent to mobile and this value may be . The caller need to trigger debug mode for each call by passing request header `x-process-debug: true` ## Use Cases The following use cases are supported: * [Onboard and Authenticate user with email/mobile and password](useCaseOnboardAuthV2EmailMobile) * [Authenticate user with email/mobile and password](useCaseAuthV2EmailMobilePw) * [Authenticate user with email/mobile and OTP and set password](useCaseAuthV2EmailMobileOtpNoPw) * [Authenticate user with AuthN ID (mobile/email) and MFA](useCaseAuthV2EmailMobileMFA) * [Authenticate user with mobile/email and FIDO2](useCaseAuthV2EmailMobileFIDO) * [Authenticate user with mobile/email and OTP/Magic Link (passwordless)](useCaseAuthV2EmailMobileOtpLinkPwLess) ## Related Topics * [Onboarding and Authentication Errors](onboardAuthV2Errors) * This Process supports clients integrating with Invisible reCAPTCHA. See [reCAPTCHA documentation](https://developers.google.com/recaptcha/docs/invisible) for more information on how to build reCAPTCHA into your application. * [Action Tokens - Proof Key for Action Tokens (PKATs)](c_actionTokens#section_irr_wss_cpb) * **[Onboard and Authenticate Process Step Interfaces](../topics/onboardAuthenticateUserV2StepInterfaces)** * **[Onboard and Authenticate with Email Address or Mobile Number](../topics/useCaseOnboardAuthV2EmailMobile)** * **[Authenticate with Email Address or Mobile Number and Password](../topics/useCaseAuthV2EmailMobilePw)** * **[Authenticate with Email Address or Mobile Number and OTP (user has no password)](../topics/useCaseAuthV2EmailMobileOtpNoPw)** * **[Authenticate with Email Address or Mobile Number and MFA](../topics/useCaseAuthV2EmailMobileMFA)** * **[Authenticate with Email Address or Mobile Number and FIDO](../topics/useCaseAuthV2EmailMobileFIDO)** * **[Authenticate Email Address or Mobile Number and OTP/MagicLink (user has password)](../topics/useCaseAuthV2EmailMobileOtpLinkPwLess)** * **[Onboarding and Authentication Errors](../topics/onboardAuthV2Errors)** **Parent topic:**[Identity Management Processes](../images/c_identityProcesses) This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.