Token-Based Authentication (TBA)

NetSuite supports Token-Based Authentication (TBA) a robust, industry standard-based mechanism that increases overall system security. This authentication mechanism enables client applications to use a token to access NetSuite through APIs, eliminating the need for RESTlets or web services integrations to store user credentials. The TBA feature was built for integrations.

Out of all the inbound single sign-on features available for use in NetSuite, TBA is the only mechanism mature enough to use with SuiteTalk (web services) and RESTlets. In your integrations, you might need to use certain functions that require an Administrator role.

Two–Factor Authentication (2FA) for Administrator roles will be enforced for all existing accounts in 2018.2. In past releases, you could not use TBA tokens for integrations that required an Administrator role. The 2018.1 release introduced support for TBA for Administrators. Using an Administrator role with a TBA token ensures your integrations will continue to work after the upgrade to 2018.2. We recommend that you transition integrations that require an Administrator role to use TBA rather than user credentials.

Token-based authentication allows integrations to comply with any authentication policy that is deployed in a NetSuite account for UI login, such as SAML Single Sign-on, Inbound Single Sign-on, and Two-Factor Authentication. You can use Two-Factor Authentication (2FA) roles and roles with SAML Single Sign-on permissions with TBA.

Password rotation policies in the account do not apply to tokens, making password management unnecessary for your RESTlet and web services integrations. Token-based authentication allows integrations to comply with any authentication policy that is deployed in a NetSuite account for UI login.

How to Enable the Token-Based Authentication Feature

First, Token-Based Authentication must be enabled in your NetSuite account.

Under Setup > Company > Setup Tasks > Enable Features, navigate to the SuiteCloud subtab and enable the required features:

Client SuiteScript (pre-requisite for Server side SuiteScript)
Server SuiteScript (pre-requisite for RESTlets)

tba-image4

Navigate to the manage authentication section and enable the Token-based Authentication if it is not already enabled.

tba-image5

How to Set Up Token-Based Authentication Roles

Token-based authentication is a per user authentication and requires certain permissions in NetSuite. An existing role can be used (recommended) or a new role can be created.

The following TBA permissions can be added to non-administrator roles when appropriate:

1. Access Token Management

Users can create, assign, and manage tokens for any user in the company.
Users cannot use token–based authentication to log into the NetSuite UI.

2. User Access Tokens

Users can create and revoke access tokens for their own use (through the Manage Access Tokens link in the Settings portlet, or by calling the token endpoint).
Use access tokens to log in through RESTlets or SuiteTalk (web services).

3. Log in using Access Tokens

Users with this permission can manage their own tokens using the Manage Access Tokens link in the Settings portlet, and they can log in using a token.

Assigning Users to Token-Based Authentication Roles

After modifying roles with the appropriate token-based authentication permissions, an account administrator can assign users to those roles.

How to Assign an Employee to a Token-Based Authentication Role:

Go to List > Employees > Employees.
Click Edit next to the name of the employee you want to assign the token-based authentication role.
Click the Access subtab.
In the Role field, select the token-based authentication role for this employee.
Click Add.
Click Save.

Two-Factor Authentication (2FA)

2FA allows enforcement of an additional level of security for logging in to NetSuite, and can protect your company from unauthorized access to data.

2FA requires users to log in using:

Something they know — NetSuite credentials (email address and password).
Something they have — A secure token that generates a time-based verification code for each login — or a mobile phone that can receive verification codes by Short Message Service (SMS) text message, voice call, or an authenticator application.

Each code is a unique series of numbers valid for a limited time, and only for a single login.

Types of Two-Factor Authentication Supported in NetSuite

NetSuite supports two types of Two-Factor Authentication:

Two-Factor Authentication by Phone or Authenticator Application, referred to as 2FA by Phone or 2FA by Authenticator App.
- SMS text messages, voice calls, and third-party authenticator applications are all supported delivery methods for verification codes, however ennVee recommends using an authenticator application.
2FA using RSA SecurID hardware and software tokens. (2FA using RSA Tokens).

About 2FA by Phone or Authenticator App

Why Use 2FA by Phone or Authenticator App in your NetSuite Account?

No special licensing or special tokens are required. (No cost).
Access is supported for the NetSuite UI and NetSuite Mobile applications.
Works with all non-customer center roles, including contacts.
Minimal maintenance is required of administrators. After being assigned to a 2FA authentication required role, users configure their own settings and manage their own devices in NetSuite.
The user’s 2FA settings are shared across all NetSuite accounts and for all companies to which they have access.

There are two authentication options available. Users can switch between these two options when they log in:

1. 2FA by Authenticator App

This option is recommended as the primary authentication method because it is always available. Even if a user cannot receive a text message (SMS) or a voice call, the authenticator app can generate a verification code.

2. 2FA by Phone

This option lets users specify their preferred delivery method for verification codes: Text message (SMS) or voice call. Users only need to set up their phone number in NetSuite and specify how they prefer to receive verification codes.

Managing Two-Factor Authentication in NetSuite

The following are required tasks for managing Two–Factor authentication in a NetSuite account. These tasks can be completed by account administrators and by other users that have the Two-Factor Authentication permission.

For roles that are to be restricted as 2FA roles, designate the type of 2FA authentication (RSA 2FA authentication required or 2FA authentication required).

When using 2FA by Phone or Authentication App, after administrators designate and assign roles to users, users:

Are sent a verification code by email during the initial login attempt to a 2FA role.
Must select their preferred authentication method.
- If the user selects 2FA by Phone, they must register their phone number in NetSuite, which is tied to their email address.
- If the user selects 2FA by Authenticator App, they must set up their chosen authenticator
Select a backup 2FA method (optional).
Are provided ten backup codes, to be used when they are not able to receive a verification code through their authenticator app, text message (SMS), or a voice call.

How to Designate Two-Factor Authentication Roles

Go to Setup > Users/Roles > Two-Factor Authentication Roles.
For roles that require 2FA, select the type of authentication (RSA 2FA authentication required or 2FA authentication required) in the Two-Factor Authentication Required column.

Image of NetSuite Two-Factor Authentication Roles Screen

In the Duration of Trusted Device column, accept the default (Per Session) or select the length of time before a device a user has marked as trusted will be subject to a two-factor authentication request.
Click Submit.

How to Set Up Token-Based Authentication for RESTlet Integration

NetSuite supports token-based authentication (TBA) a robust, industry standard-based mechanism that increases the overall security of the system.

This authentication mechanism enables client applications to use a token to access NetSuite through APIs, eliminating the need for RESTlets to store user credentials. A token is valid for one specific company, user entity, and role only.

When you use token-based authentication, password rotation policies in the account do not apply to tokens and password management is unnecessary for your RESTlets integrations. Token-based authentication allows integrations to comply with any authentication policy that is deployed in a NetSuite account for UI login, such as SAML Single Sign-on, Inbound Single Sign-on, or Two-Factor Authentication.

You can create a token and assign it to a user by logging in to NetSuite as an administrator and generating token credentials manually. NetSuite users can also generate token for themselves.

Authentication for RESTlets

RESTlets must use rest URLs to connect to NetSuite. If the RESTlet call comes from an external client, the URL must include a domain specific to your NetSuite account.

This domain can change without notice. For that reason, you must dynamically discover the correct domain when calling RESTlets from an external client. To handle this task, use the roles service, as described in The REST roles Service.

For a RESTlet called from an external client, you can use OAuth.OAuth uses token-based authentication (TBA) to access resources on behalf of a user, eliminating the need to share login credentials such as user name and password.

Using OAuth in the Authorization Header

OAuth Passes in the Following Parameters:

oauth_signature (required) Credentials to verify the authenticity of the request, generated by calling your application. The Token Secret and Consumer Secret are constructed as a key to sign the request, using a supported signature method (HMAC-SHA1 or HMAC-SHA256).
oauth_version (optional) Must be set to “1.0”
oauth_nonce (required) Passes in a unique, random, alphanumeric string. String must be a minimum of 6 characters, and the maximum length is 64 characters. Used to verify that a request has never been made before.
oauth_signature_method (required) Must be set to HMAC-SHA1 or HMAC-SHA256. Declares which signature method is used.
oauth_consumer_key (required) Consumer Key (client application ID) generated for the token-based application in NetSuite. The unique value is matched to the token to establish ownership of the token.
oauth_token (required) Token ID generated for the token-based application in NetSuite.
oauth_timestamp (required) Passes in a positive integer expressed as the number of seconds since January 1, 1970 GMT.
realm (required) NetSuite company ID

Here is an Example RESTlet Request using OAuth to access a Protected Resource:

GET https://rest.na1.netsuite.com/app/site/hosting/restlet.nl?script=1&deploy=1 HTTP/1.1

Authorization:

OAuth oauth_signature=”MgN1gZztYspNQXA576plPD14OWM%3D”,

oauth_version=”1.0”,

oauth_nonce=”207310548”,

oauth_signature_method=”HMAC-SHA1”,

oauth_consumer_key=”fvFwnmvurChjol7SZiF2pQ1oJ%2FceRV8vqA%2FrZtzLEo%3D”,

oauth_token=”00076e1415667a6c555f5d43582134c87d6367ab456fd2”,

oauth_timestamp=”1418647040”,

realm=”000068”

Creating Applications for Token-Based Authentication

Applications must be created with the Integration record for use with token-based authentication before tokens can be created and assigned to users. Administrators or users assigned the full level of the Setup Type Integration Application permission can create applications for use with token-based authentication.

How to Create an Application using the Integration Record:

Go to Setup > Integration > Manage Integrations > New
Enter a Name for your application.
Enter a Description, if desired.
The application State is Enabled by default. (The other option available for selection is Blocked.)
Enter a Note, if desired.
Check the Token-based Authentication box on the Authentication subtab.

Click Save. The confirmation page displays the Consumer Key and Consumer Secret for this application.

Click List to view all Integrations in your account.

Managing TBA Tokens

Managing TBA tokens in your account includes the following:

Viewing, Editing, and Revoking Tokens
Searching for tokens in your account
Creating Tokens — There are various methods for creating tokens. In the NetSuite User Interface, the method employed depends on the permission assigned to the role. Users can also create tokens without logging in to the NetSuite UI.

For more information, refer to the following topics:

Access Token Management — Create and Assign a TBA Token

User Access Token — Create a TBA Token

TBA — Token Endpoint

Create and Assign a TBA Token

Users assigned a role that has the Access Token Management permission can create, assign, and manage a token for any user in the company. For example, they could assign a token to those users who are assigned a role with only the Log in using Access Tokens permission.

How to Create and Assign a TBA Token:

Log in as a user with the Access Token Management permission.
Go to Setup > Users/Roles > Access Tokens > New.
On the Access Tokens page, click New Access Token. The Access Token page displays the following:

On the Access Token page:

Select the Application Name > Select the User > Select the Role.
The Token Name is already populated by default with a concatenation of Application Name, User, and Role. Enter your own name for this token, if desired.

Click Save. The confirmation page displays the Token ID and Token Secret.

Viewing, Editing, and Creating TBA Tokens

You can see a list view of tokens in your system.

How to View Tokens:

Go to Setup > Users/Roles > Access Tokens ( Administrator ).

(Alternatively, you can go to Setup > Other Setup > Access Tokens).

The Access Tokens page displays the following:

tba-image12

Revoking TBA Tokens

Revoking a token makes it inactive forever, but does not remove the token from the system. The token is still accessible for auditing purposes.

Revoke and Inactive Statuses

When a token is revoked, it cannot be edited, and will display with an Inactive status in list views. When the Inactive box is checked for a token, the token will display as Inactive in list views, but the token can still be edited. To make the token active again, click Edit, clear the Inactive box, and click Save.

tba-image13

Other Scenarios when Tokens are Revoked

Scenario 1 — When an application used for token-based authentication is deleted, all tokens associated with that application are revoked.

Scenario 2 — When an administrator removes roles from an entity (an employee, a vendor, a partner, a customer, or a contact) the tokens are still active in the system. These active tokens cannot be used by the entity for log in to NetSuite (unless the administrator adds the roles back to the entity).

Scenario 3 — When an administrator deletes an entity, (an employee, vendor, partner, customer, or contact), the associated tokens are revoked.

NetSuite Token-Based Authentication Assessment Guide

Contents