OAuth 2.0 for NetSuite - Part One

What is OAuth 2.0?

Everybody loves a good definition. We could not start this NetSuite OAuth 2.0 deep dive without defining what OAuth actually is. Here are some definitions from various sources:

OAuth Spec (RFC6749)

The OAuth 2.0 authorization framework enables a third-party application to obtain limited access to an HTTP service, either on behalf of a resource owner by orchestrating an approval interaction between the resource owner and the HTTP service, or by allowing the third-party application to obtain access on its own behalf.

Wikipedia

OAuth (short for open authorization) is an open standard for access delegation, commonly used as a way for internet users to grant websites or applications access to their information on other websites but without giving them the passwords

ChatGPT

OAuth 2.0 is an open standard protocol that allows applications (clients) to obtain limited access to a user’s resources on another service (like Google, GitHub, or NetSuite) without needing the user’s credentials (like username and password)

Claude

OAuth 2.0 is an authorization framework that allows applications to obtain limited access to user accounts on other services without exposing the user's credentials. It's the industry standard for secure API authorization.

Admittedly, some of the above definitions aren't the easiest to digest. But notice that they all use common terms:

• Authorization
• Access / Limited Access
• Resource
• Service
• Grant
• Credentials
• Client
• User

Here is my own, simpler definition:

OAuth 2.0 is a framework which makes it possible for a user to grant a 3rd party the ability to access data they own and manage in some service.

And another one using all the above terms:

The essence of OAuth is basically some user giving a client application, access to protected resources on some service, using an access token issued by an authorization server, after the client has received an authorization grant via the user’s approval..

If after 6 definitions you're no closer to understanding what OAuth is, least not NetSuite OAuth, don't worry. By the end of this series you will have a really good grasp of the framework, and how to wield it in a NetSuite context and beyond.

Why OAuth 2.0?

Giving 3rd party applications access to use your data can be very useful. 

Think of a service like Calendly having the ability to read a list of all your meetings via your calendar, to display your availability to prospective clients. 

In the NetSuite world, think of a service like say, oh I don't know.... Bundlet, accessing your File Cabinet, to produce all kinds of useful cross account script comparisons.  

Think Claude gaining access to your NetSuite account to do its thing.

OAuth is the underlying framework that facilitates the sharing of this data, and it is literally everywhere.

Historically, whenever a user wanted to grant access to resources they own, they had to share their credentials (mostly password) with all such applications. And since sharing that same data with multiple third party applications could be useful, that meant sharing those same credentials with all would-be consumers. This posed several challenges:

1. Passwords are inherently insecure, just ask Yubico
2. Sharing your password with anyone is bad, sharing it with everyone is even worse, increasing the number of potential weak links
3. Sharing your password gives access to the entire account's data - you cannot limit the access to just the data the service needs
4. Revoking access for one client means revoking for all

Apart from the above drawbacks, with this simplistic approach for granting access to data, there is essentially no distinction or separation of roles between the owner of the data, and any other 3rd party having the password to access that service.

OAuth sought to separate the roles of the application wanting to access data on the owner’s behalf, and the owner himself. This approach casts additional actors to this data sharing dialogue, and understanding their roles is key to following along.  Many tutorials on OAuth seem to substitute the role names included in the RFC for other 'friendlier' alternatives, but I actually think they’re rather well laid out and for the most part will reference the terms as they are.

Access to protected resources. This is the ultimate goal of the framework - giving access to data.  

Of course this data is usually private, hence the term protected, and since it’s private someone, rather, the Resource Owner, needs to grant access to this data.  In most cases the resource owner is usually a person or end-user.  So the resource owner is simply the person owning the data.

In the Calendly example that’s whoever wants customers to book time in their calendar.  In the Bundlet example, that’s you, esteemed reader, who would like to backup your scripts and objects to Git, and in the case of using the NetSuite AI connector service, that again is you or your company. 

So officially the Resource Owner is:

An entity capable of granting access to a protected resource. When the resource owner is a person, it is referred to as an end-user

Now all data / resources need to be hosted somewhere.  Your Calendar data is hosted by Google, NetSuite Scripts, Objects and Financial data are hosted by NetSuite.  Protected resources need to live somewhere, and that somewhere is the Resource Server.  In order for protected resources to be shared, someone or something needs to allow access and serve requests for this data.  Therefore the Resource Server is:

The server hosting the protected resources, capable of accepting and responding to protected resource requests using access tokens.

Of course the resource server will not just grant access to our end user’s lovely data to just anyone all of the time, and that is why reference above to Access Tokens is made.

Now all data / protected resources being served by the resource server need to be served to some entity.  Our resource server does not just serve data to thin air, and this is where the Client or application enters the stage.  This is more often than not a 3rd party application wanting to access data / protected resources on your behalf.  Calendly, Claude and Bundlet.

Calendly can never request my calendar data without me as the Resource Owner / End-User authorizing it to do so.  Therefore a Client is:

An application making protected resource requests on behalf of the resource owner and with its authorization.  The term "client" does not imply any particular implementation characteristics (e.g.,whether the application executes on a server, a desktop, or other devices).

I love these definitions because they are extremely precise. Note the comment on the Client not implying any implementation characteristics.

For now to summarize, just remember that with these Roles in place, there is a clear distinction between the Resource Owner and a 3rd Party Application in the eyes of the Resource Server.  The 3rd Party application now uses an access token it has been authorized to use when requesting data from the server.

That is it for part one.  We’ve deliberately omitted the last important Role in all this, the Authorization Server.  Part two will begin with what role the Authorization Server plays in the OAuth dance, and a detailed description of every interaction between these Roles that leads to the generation of an Access Token, aka the Protocol Flow.