Learn how to integrate the client-side web SDK into your web application
@prove-identity/mobile-auth
. Install the client-side SDK of your choice by running a command in your terminal, or by using a dependency management tool specific to your project.
skipLibCheck
setting in your tsconfig.json
file:.d.ts
files) from external libraries, which resolves the compilation issues while maintaining type safety for your own code.Affected Versions:isMobile
is true, pass mobile
to the Start()
function on the server, otherwise you can pass desktop
:
AuthFinishStep
function finishes.
ERR_TUNNEL_CONNECTION_FAILED
- this is due to the VPN, but the SDK fallbacks to OTP.AuthFinishStep
function finishes.
Authenticate()
authToken
as a parameter for the Authenticate()
function. This token returns from the Start()
call of the server-side SDK. The token is session specific, limiting it to a single flow. It also expires after 15 minutes.
authToken
authToken
, build the authenticator for both the mobile and desktop flows.
https://device.uat.proveapis.com:4443
https://device.uat.proveapis.com
http://device.uat.proveapis.com:4443
http://device.uat.proveapis.com
https://device.proveapis.com:4443
https://device.proveapis.com
http://device.proveapis.com:4443
http://device.proveapis.com
https://auth.svcs.verizon.com:22790
AuthFinishStep
, you’ll specify a function to call once the possession checks complete on the mobile phone. This endpoint on your back end server calls the Validate()
function to validate the phone number. If it was successful, the server returns the results from the Challenge()
function including customer information. Refer to the following example fields that return and then prefill on a form for the customer to verify. The AuthFinishStep
then completes. In the event of cancellation, the server makes a call to the Validate()
function and returns success=false
.
withOtpFallback(startStep: OtpStartStep | OtpStartStepFn, finishStep: OtpFinishStep | OtpFinishStepFn)
, requires implementing the OtpStartStep
and OtpFinishStep
. When returning the phone number in the functions, ensure you return an object with the field phoneNumber
to the resolve()
function. The default implementation is below, but you can also view the other tabs if you wish to enable advanced capabilities.
The OTP session has a two minute timeout from when it’s sent through Short Message Service (SMS) to when the customer can enter in the OTP.
/v3/start
endpoint. In this case, you’ve already prompted for a phone number so you don’t need to prompt for it in the client SDK.Since you passed the phone number in the Start()
function, call resolve(null)
to communicate to the SDK you have the customer’s agreement to deliver the SMS message. Ensure you return an object to resolve()
function.reject('some error message')
method to communicate to the SDK any issues while trying to obtain the phone number or the OTP. Report an error if the customer cancels the SMS transaction or presses the back button to leave the screen.In the finish step, call the resolve(result: OtpFinishResult)
method to return the collected OTP value in which result
variable has OnSuccess
value for OtpFinishResultType
and the OTP value wrapped in OtpFinishInput
.withInstantLinkFallback(startStep: InstantLinkStartStep | InstantLinkStartStepFn, retryStep?: InstantLinkRetryStep | InstantLinkRetryStepFn)
requires implementing the InstantLinkStartStep
interface and optionally the InstantLinkRetryStep
interface if you wish for advanced capabilities. When returning the phone number in the functions, ensure you return an object with the field phoneNumber
to the resolve()
function.
The Instant Link session has a three minute timeout from when it’s sent through Short Message Service (SMS) to when the customer can click the received link.
/v3/start
endpoint. In this case, you’ve already prompted for a phone number so you don’t need to prompt for it in the client SDK.Since you passed the phone number in the Start()
function, call resolve(null)
to communicate to the SDK you have the customer’s agreement to deliver the SMS message. Ensure you return an object to resolve()
function.Complete()
call can then verify the customer information.
Authenticator.authenticate()
, while creating an instance of Authenticator using AuthenticatorBuilder.build()
.
Use the following methods to configure Authenticator
before instantiating. All methods return the same instance of AuthenticatorBuilder
to allow chaining of the configuration methods.
withAuthFinishStep(step: AuthFinishStep | AuthFinishStepFn): AuthenticatorBuilder
This step customizes the handling of the authentication finish call. The implementation calls the customer’s back end to retrieve authentication results. The customer defines the format of the response to suit the application needs.
withRole(role: DeviceRole): AuthenticatorBuilder
Sets the authentication role for this device. It can be either Primary
or Secondary
. The Primary
value sets when the customer is on a mobile device web browser that registers with the Prove system and later authenticated by verifying this registration. On other hand, the Secondary
value sets when the customer is on a desktop web browser, which authenticates after receiving customer feedback on their Primary
device.
withMobileAuthImplementation(implementation: MobileAuthImplementation): AuthenticatorBuilder
Sets the implementation type for Mobile Auth authenticator. Possible values are Fetch
or Pixel
with Fetch
set by default.
withDeviceIpAddress(deviceIp: string | (() => string | null) | null): AuthenticatorBuilder
Sets the public IP address for this device to report during device registration. If you neglect to call this method, or the IP address value is null
, the system attempts to autodetect the IP address using an external service. If the service is inaccessible, the system uses the client’s IP address of the HTTP connection. Successful Mobile Auth authentication requires the client’s public IP address.
withOtpFallback(startStep: OtpStartStep | OtpStartStepFn, finishStep: OtpFinishStep | OtpFinishStepFn): AuthenticatorBuilder
Configure start and finish handlers for SMS OTP authenticator. Collecting customer input requires using these handlers to enter the phone number for delivery of OTP codes, and to enter received OTP codes.
withInstantLinkFallback(instantLinkStartStep: InstantLinkStartStep | InstantLinkStartStepFn, instantLinkRetryStep?: InstantLinkRetryStep | InstantLinkRetryStepFn): AuthenticatorBuilder
Configure handler for Instant Link authenticator. This handler collects customer input to enter the phone number for Instant Link.
build(): Authenticator
Finalizes the configuration and returns an instance of the Authenticator
.