How Can I Setup A Connection To NetSuite Using Certificates?

How Can I Setup A Connection To NetSuite Using Certificates?

Overview
By adding a NetSuite connection to your workspace, you can:
  1. Automatically import and sync sales transactions to your workspace
  2. We support any SuiteQL query as long as we can incrementally retrieve data (details)
  3. Newly created NetSuite records will be synched to your workspace
  4. Modified NetSuite records will be updated in your workspace
  5. Deletion of NetSuite records will not result in any deletion in your workspace
  6. NetSuite records no longer matching your SQL query will not result in any deletion in your workspace
This article describes how to connect using an X509 certificate. A certificate provides a long-lasting connection that does not require weekly re-authorization. If you prefer to use a Token-Based Authentication (TBA) instead, please see How Can I Setup A Connection To NetSuite Using Token-Based Authentication (TBA)? 

Unlike most other CRM or Accounting platforms, NetSuite requires more significant setup to enable authorization. 

We will show you:
  1. How to enable NetSuite features
  2. How to enable sufficient permissions
  3. How to create an integration record
  4. How to enable Machine-to-Machine authentication

Step 1 - In Sales Cookie, Create a NetSuite Connection
To create a connection to NetSuite:
  1. Login to your workspace
  2. Navigate to Settings > Connections using the left navigation bar
  3. Click on NetSuite
You should see this screen:


Keep this browser window open, as you will copy/paste values from NetSuite.

Step 2 - In NetSuite, Enable Features
For OAuth authentication and REST Web Services to work, NetSuite requires certain features to be enabled (reference).

To enable those features:
  1. Login to NetSuite
  2. Go to Setup > Company > Enable Feature
  3. Click on the 'SuiteCloud' tab
    1. Enable SuiteScript > Client SuiteScript & Server SuiteScript
    2. Enable SuiteTalk > Rest Web Services
    3. Enable Manage Authentication > OAuth 2.0
  4. Go to Setup > Company > Enable Feature
  5. Click on the 'Analytics tab' tab
    1. Enable SuiteAnalytics Workbook > SuiteAnalytics Workbook

Step 3 - In NetSuite, Ensure Sufficient Permissions
For OAuth authentication and REST Web Services to work, NetSuite requires your account to have sufficient permissions (reference, reference).

To grant permissions:
  1. Login to NetSuite
  2. Go to Setup > Users/Roles > Manage Roles
  3. Choose a role
    1. We recommend the accountant or sales manager roles
    2. You can also create a new role - make sure to grant access to all relevant entities (Transactions, Users, Items, etc.) 
  4. In the 'Permissions' section
    1. Select Permissions > Reports
      1. Grant permission 'SuiteAnalytics Workbook (edit)'
    2. Select Permissions > Setup 
      1. Grant permission 'Log in using OAuth 2.0 Access Tokens'
      2. Grant permission 'User Access Token'
      3. Grant permission 'OAuth 2.0 Authorized Applications Management'
      4. Grant permission 'REST Web Services (full)'
      5. Grant permissions 'Custom Fields (view)' and 'Custom Lists (view)', 'Custom Record Types (view)'
  5. Make sure the role you edited is applied to your user account

Step 4 - In NetSuite, Create An Integration Record
For OAuth authentication and REST Web Services to work, NetSuite requires creating an integration record representing the connected application (reference).

To create an integration record:
  1. Login to NetSuite
  2. Go to Setup > Integration > Manage Integrations > New
  3. Name your integration 'Sales Cookie'
  4. Ensure the 'State' is 'Enabled'
  5. Uncheck  'TBA: Authorization Flow'
  6. Uncheck 'Token-Based Authentication'
  7. Under OAuth 2.0
    1. Check 'Authorization Code Grant'
      1. Ensure there is no trailing space or slash
    3. Under 'Scope', check 'REST Web Services'
  8. Check 'Client Credentials (Machine to Machine) Grant'
    1. This step is required if you do not want to re-authenticate every week
    2. Further details are provided in Step 6 below
  9. Save your integration record
  10. Save the displayed Client ID and Secret (you will need them later)
    1. They are displayed at the end of the page after saving

Step 5 - In Sales Cookie, Enter Credentials
You are now ready to test your connection in Sales Cookie:
  1. Return to Sales Cookie (Settings > Connections > NetSuite)
  2. Enter your Client ID and Secret from step 4
  3. Enter your Account ID
    1. If your NetSuite URL is https://1234.app.netsuite.com/app, your account ID is 1234
    2. Make sure to use the same casing as in your URL
  4. Click on Save
  5. You should see an 'Authorize Access' button

  6. Click on the button and follow the workflow to authorize access
Warning
Important - this access method limits access to 1 week, after which manual re-authentication is required. For longer-lasting connections, please use the following additional steps.

Step 6 - In NetSuite, Enable Machine-to-Machine (M2M) Authentication
Without this step, you will need to manually re-authorize access in Sales Cookie every week as NetSuite OAuth only grants refresh tokens for 1 week (this cannot be extended). NetSuite offers a way to connect for longer periods of time. This is something called either 'Machine-to-Machine (M2M) Authentication' or 'OAuth 2.0 Client Credentials' (reference, video).

First, generate an X509 certificate (reference):
  1. Download openssl
    1. This is a tool to generate X509 certificates
  2. Run this command
    1. openssl req -new -x509 -newkey ec -pkeyopt ec_paramgen_curve:secp521r1 -nodes -days 729 -out public.pem -keyout private.pem
    2. Enter your organization name, email, etc.
    3. A public.pem and private.pem files should be generated

Our support team can also generate a unique certificate for you.
 
Second, enable M2M authentication (reference, video):
  1. Login to NetSuite
  2. Go to Setup > Integration > Manage Authentication > OAuth 2.0 Client Credentials (M2M) Setup
  3. Click on 'Create New'
  4. For the 'Entity', select yourself
    1. The selected account must have sufficient permissions - see step 3
  5. For the 'Application', select the 'Sales Cookie' integration record
    1. This assumes you named the integration 'Sales Cookie' - see step 4
  6. Select a role with sufficient permissions
    1. The selected role must have sufficient permissions - see step 3
  7. Upload public.pem generated previously
  8. Click on 'Save'
  9. Save the displayed Certificate ID (you will need it later)
    1. The certificate ID is in the first column of the displayed table

Step 7 - In Sales Cookie, Enable Machine-to-Machine (M2M) Authentication
Without this step, you will need to manually re-authorize access in Sales Cookie every week as NetSuite OAuth only grants refresh tokens for 1 week (this cannot be extended). NetSuite offers a way to connect for longer periods of time. This is something called either 'Machine-to-Machine (M2M) Authentication' or 'OAuth 2.0 Client Credentials' (reference, video).

Enable M2M authentication:
  1. Return to Sales Cookie (Settings > Connections > NetSuite)
  2. Click inside the dotted box

  3. Upload private.pem generated previously
  4. Paste your Certificate ID from step 6

  5. Click on Save
  6. Click on Test to verify the connection


Allocating Sufficient Capacity
NetSuite has a quota for the number of REST Web Service calls integrations can make (reference). Ongoing synchronization cycles will be small because only new or modified data is queried (incremental sync). However, the initial synchronization cycle is heavier, as all your historical data must be synchronized.

To increase quotas:
  1. Login to NetSuite
  2. Go to Setup > Integration > Integration Management > Integration Governance
  3. Increase concurrency limits

Troubleshooting Access Problems
There is an audit trail in NetSuite (reference):
  1. Login to NetSuite
  2. Go to Setup > Users/Roles > User Management > View Login Audit Trail
  3. Check the 'Use Advanced Search' box (customize the search)
  4. Click the 'Results' sub-tab
  5. Add the following fields: 'Detail' and 'Token-based Application Name' (see screenshot below)
  6. Filter to 'Status' = 'Failure'
  7. Click on Submit
The Detail column displays error messages for any OAuth 2.0 logins with a status of 'Failure'. 
For more information about defining Login Audit Trail searches, see Login Audit Trail Overview.