Required 2FA, the IssueToken Endpoint, and nlauth_otp
You should use The Three-Step TBA Authorization Flow for all new TBA integrations. You should also consider migrating existing integrations currently using the issutoken endpoint to use the authorization flow.
To accommodate the requirement for required 2FA for highly privileged roles, the issuetoken endpoint was extended. The NLAuth authentication header includes an optional parameter, nlauth_otp. You can use the nlauth_otp parameter to include a one-time password (OTP) in the NLAuth header. The OTP is equivalent to the 2FA verification code provided by a user logging in to the NetSuite UI. Users can generate the necessary codes using an authenticator app, such as Google Authenticator, Microsoft Authenticator, or Okta Verify. The authentication application you choose must support OATH TOTP, the IETF RFC 6238 standard. Go to https://tools.ietf.org/html/rfc6238 to review the standard.
If the authenticator app is on the same device you use to access the integrations, it is not considered secure. Similarity to the 2FA verification code can only be maintained if the authenticator and the integration are not on the same device.
An authenticator app is configured for and linked to a user’s email address. The verification code must be synchronized to the email address used in the NLAuth header for the integration.
An authenticator app must generate the verification code included in an NLAuth header. Verification codes such as those supplied by an email, SMS message, voice call, or from a backup code are not acceptable.
The one–time password (OTP) is a TOTP: a time-based one-time password. Time-based means that the verification code must be generated at the time of need: when the request is sent and being authenticated. The verification code is valid for approximately a minute surrounding the time of authentication. The validity window may vary depending on the implementation.
If the NLAuth authentication header does not include an OTP for a 2FA required role, the user receives an error message that two-factor authentication is required.
Supplying Verification Codes
You must provide a method to supply the verification code in the NLAuth header. There are two ways to implement a method for generating the necessary verification code. See the following sections for more information:
Manual Method for Supplying Codes
You can use the manual method when interaction with a human is possible. You could code a pause into your integration and ask users to supply a verification code from their authenticator app. Users must have already configured their 2FA settings in NetSuite.
Automated Method for Supplying Codes
You must use an automated method when interaction with a human is not possible. You could implement a generator of OTPs. The implementation of TOTP in NetSuite is based on RFC 6238 https://tools.ietf.org/html/rfc6238. This specification has a reference implementation.
-
The code generator must store one secret key per user, that is, per email address. (When a user is configuring 2FA settings in NetSuite, the secret key is the long string of characters shown next to the QR code displayed on the Two-Factor Authentication setup page. If a user resets 2FA settings, the secret key has a different value when 2FA is configured again.
Important:Each implementation of an authenticator app may have a different number of digits for the verification code, and a different validity window. The validity window is the length of time that the code is valid. The NetSuite implementation accepts a six-digit verification code, and the code is valid for 30 seconds.
-
If the time is not perfectly synchronized, plus or minus a few seconds should not cause a verification code to be rejected.
-
Each code can be used only a single time. If two integrations hit the issuetoken endpoint with the same verification code for the same user at the same time (within 30 seconds) then the second integration will fail. To avoid this situation, the best practice is to use various users and roles for multiple integrations. Otherwise, you must include logic in your code that forces the client to wait 30 seconds and use the next available code.
For more information about the NLAuth authentication header and the issuetoken endpoint, see Using User Credentials for RESTlet Authentication. See also Issue Token and Revoke Token REST Services for Token-based Authentication.