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 for integrations, it isn’t considered secure. You can only keep 2FA verification secure if the authenticator and the integration aren’t 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, which means it’s a time-based one-time password. Time-based means you have to generate the verification code right when you send and authenticate the request. The verification code’s good for about a minute around the time you authenticate. The exact time window can vary depending on how it’s set up.
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 you’re able to interact with a person. You could add a pause in your integration and ask users for a verification code from their authenticator app. Users need to have their 2FA settings set up in NetSuite first.
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 needs to store one secret key for each user—that is, for each email address. (When you set up 2FA in NetSuite, the secret key is the long string of characters next to the QR code on the setup page.) If you reset your 2FA settings, the secret key changes the next time you set up 2FA.
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 isn’t perfectly synced, being off by a few seconds shouldn’t cause a verification code to get rejected.
-
Each code can only be used once. If two integrations use the issuetoken endpoint with the same code for the same user at the same time (within 30 seconds), the second one will fail. To avoid this, it’s best to use different users and roles for each integration. Otherwise, you’ll need to add logic to your code to make the client 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.