External multi-factor authentication integration

Edit online

Use the following information and guidance to customize the IBM® Verify Webhooks feature for external multi-factor authentication (MFA) integration.

External MFA overview

IBM Verify supports and provides an integration framework to enable integration with other external MFA providers. The following diagram illustrates the main components of an end to end external MFA integration flow.

The image shows the flow from the application in the browser to the external MFA provider.

External MFA runtime challenge user experiences can be integrated with the Verify MFA features and any other external MFA providers. The runtime experience can be driven by Verify federated single sign-on and access policy capabilities, which include template page customizations. Additionally, external MFA challenges can be driven and started by new Verify MFA APIs.

Enable an external MFA provider in ISV by configuring these two configuration objects:
MFA Provider
Provides the Verify public access and runtime for the external MFA provider and must be associated with a real-time webhook configuration instance.
Real-time webhook
Provides the Verify internal components with access to the target MFA provider over the public internet. The webhook provides HTTPS client connectivity to the external MFA provider. The configuration handles the following aspects:
  • The public internet location addresses where the provider can be contacted.
  • Secure authentication and connection to external provider web APIs.
  • Request and response transformation and mapping.
  • A set of API resources that the Verify internal runtime components can start.

Many external MFA integrations can be achieved by using the configuration and data transformation capabilities that are provided by those two components. Some integrations and external providers might not be able to use that method. It might be necessary to adapt the external provider API with the implementation, deployment, and support of a "mediator" component between the Verify Webhooks and the target external MFA provider. The mediator runs in an infrastructure separate from Verify and possibly separate from the target MFA provider. Discussion and description of such mediators is beyond the scope of this document other than discussion of the API contract that must be implemented that enables Verify to integrate with an external provider external as a client of the provider.

MFA integration patterns

The MFA framework and runtime within Verify is based on the concepts and the ability to support integration patterns. The MFA patterns include the following capabilities:
Lookup MFA enrollments
When a user is challenged for MFA, Verify can offer the user a selection of their known, enrolled, or available MFA factors. Verify performs a "lookup" of the authenticated user's MFA capabilities and factors from an external MFA provider.
Validate only
This MFA pattern is typically a TOTP. The user already has possession of the values or tokens to be validated and submits them to the validation channel, which is typically the users current authenticated channel, for example, a browser. No separate token "delivery" occurs at run time for this MFA pattern.
Initiate (or deliver) + Validate
This MFA pattern is commonly used with factors such as SMS and email OTP. It is a two-step interaction:
  1. Initiates the delivery of a short-lived secret value or other token to the user through some delivery channel in exclusive possession or ownership of the user. The step is performed by the channel, typically the users presently authenticated channel such as a browser, that also validates the secret after its delivery.
  2. Validates that the user received the correct secret value from the previous step. Usually display some data entry prompt to allow the user to type the value received. Validation is typically performed in the users presently authenticated channel.
Initiate (or deliver) + Wait for result
This pattern is typical for mobile push authenticators. From the perspective of the relying channel, it is a two-step interaction.
  1. The presently authenticated primary channel initiates the delivery of a mobile push or other notification to the users registered mobile device.
  2. The primary channel then waits, typically by polling, for a completion state from a second channel. The MFA validation is usually performed and completed in a separate channel (the mobile device channel).

When you design and develop new external MFA integrations, adhere to these integration patterns. Almost all integrations must support Lookup MFA enrollments and at least one of the other three patterns. These patterns form the basis of the Verify external MFA API contract. See IBM Verify external MFA integration API contract.