Class: OTPStrategy
Defined in: auth/src/auth/OTPStrategy.ts:105
Implements an strategy for authenticating a user with a One Time Password (OTP) that is sent to one of the user's verified contact methods. This allows for implementation of a password-less login flow. This strategy requires that an existing user account has already been registered with at least one verified contact method.
This strategy should not to be confused with Time-Based One Time Password (TOTP) authentication which uses a
pre-shared security key, often stored on the user's device (e.g. authenticator app) or digital vault (e.g. 1Password,
Bitwarden, etc.). For TOTP authentication, see TOTPStrategy.
The login flow has three phases:
- Discovery - The client requests a list of contacts for a given user id. The
getContacts()callback is used to return the list of contacts. - Challenge - The client requests a OTP token to be sent to the contact with a specified id, optionally naming
the delivery
channel(e.g.whatsapp) when the contact supports more than one. The OTP token is generated and sent to the contact using thenotify()callback and stored in the session. - Verify - The client submits the OTP token and contact id. The OTP token is verified against the one stored in the
session, and the associated user is resolved using the
getUser()callback.
The client sends request data either in the Authorization header or the request body in standard form-data format
(e.g. id=<id>&token=<otp>). For example, the initial challenge request (step 2) can be sent as
Authorization: otp id=<contact_id> (or id=<contact_id>&channel=whatsapp). The final verification request (step 3) is then sent as
Authorization: otp id=<contact_id>&token=<otp>.
WARNING: Allowing discovery (setting OTPStrategyOptions.allowDiscovery to true) is a potential side-channel
attack allowing anyone to discover or gather partial contact information about a given user. For improved security,
the returned list of contacts is partially obfuscated. However, enough information is still provided that an
attacker may be able to harvest information anyway. For example, a phone number will be obfuscated from
818-867-5309 to ****5309. An email address will be obfuscated from john.smith@gmail.com to
j****th@gmail.com.
Implements
AuthStrategy
Constructors
Constructor
new OTPStrategy(
options):OTPStrategy
Defined in: auth/src/auth/OTPStrategy.ts:110
Parameters
options
Returns
OTPStrategy
Properties
name
readonlyname:string="otp"
Defined in: auth/src/auth/OTPStrategy.ts:106
The unique name of the strategy used to register with the AuthMiddleware.
Implementation of
AuthStrategy.name
Methods
authenticate()
authenticate(
req,res,required?):Promise<AuthResult|undefined>
Defined in: auth/src/auth/OTPStrategy.ts:115
Attempts to perform authentication with the given request data. If authentication was successful, returns an
AuthResult containing the authentication details. If authentication fails and required is set to true
throws an error, otherwise returns undefined.
Parameters
req
HttpRequest
The request containing data to attempt authentication with.
res
HttpResponse
The response to use when writing back directly to the client.
required?
boolean
Returns
Promise<AuthResult | undefined>
Implementation of
AuthStrategy.authenticate
authenticateSync()
authenticateSync(
req,res,required?):AuthResult|undefined
Defined in: auth/src/auth/OTPStrategy.ts:145
Attempts to perform authentication with the given request data. If authentication was successful, returns an
AuthResult containing the authentication details. If authentication fails and required is set to true
throws an error, otherwise returns undefined.
This is the synchronous version of authenticate that performs blocking based authentication.
Parameters
req
HttpRequest
The request containing data to attempt authentication with.
res
HttpResponse
The response to use when writing back directly to the client.
required?
boolean
Returns
AuthResult | undefined
Implementation of
AuthStrategy.authenticateSync
challenge()
protectedchallenge(payload,req,res):Promise<any>
Defined in: auth/src/auth/OTPStrategy.ts:165
Parameters
payload
any
req
HttpRequest
res
HttpResponse
Returns
Promise<any>
discovery()
protecteddiscovery(req,res):Promise<any>
Defined in: auth/src/auth/OTPStrategy.ts:149
Parameters
req
HttpRequest
res
HttpResponse
Returns
Promise<any>
verify()
protectedverify(payload,req,res):Promise<JWTUser|undefined>
Defined in: auth/src/auth/OTPStrategy.ts:198
Parameters
payload
any
req
HttpRequest
res
HttpResponse
Returns
Promise<JWTUser | undefined>