OAuth 2.0 for NetSuite - Part Two - Protocol Flow

Welcome to part 2 of the Bundlet Oauth2.0 for NetSuite series.  In the last part, I gave a brief history to the background of OAuth2.0 and what problems brought it into being.  The main focus of part one however was to introduce the Roles involved as they are laid out in the spec.  Definitely read part one if you’ve missed it, however here are the key takeaways:

OAuth 2.0 lets users grant third-party apps limited access to their data without sharing their passwords. The specification names 4 different Roles involved in brokering this exchange of data.  The Client being the application requesting access to data, the Resource Owner being the entity or end-user owning that data, and the Resource Server being the service or server hosting that data and granting the Client access to it.  The Resource Owner authorizes the Client to access the data, and the Client obtains an Access Token which it then uses to make protected resource requests from the Resource Server.

There is one more Role involved in the journey to a Client obtaining an Access Token it can use to retrieve the data it is after.  And it relates to who or what generates the Access Token among other things as you will see.  The Access Token is not handed out directly by the Resource Owner.  This is where the Authorization Server comes into play.

Now for a short detour for some more definitions; we love definitions! 

We would be remiss if we didn’t clearly define the meaning of the word Authorization.  After all it is in the name, Open Authorization Framework, or OAuth in short. But, to understand the meaning of Authorization we must first understand what it means to Authorize.

To give official or formal permission (or approval) for an action (or undertaking) - Oxford Dictionary

Some random examples of its use:

1937
“With regard to the handling of my work, I am prepared to authorize you to take up the matter with film studios.”
A. Huxley, Letter 12 July (1969) 423

1855
A royal message authorising the Commons to elect another Speaker.
T. B. Macaulay, The History of England from the Accession of James II vol. IV. 551

With the above in mind, an Authorization is therefore:

The action of authorizing a person or thing, or the formal permission or approval - Oxford Dictionary

or

Official permission for something to happen, or the act of giving someone official permission to do something - Cambridge dictionary

and we couldn’t leave out a definition from our favourite LLM:

“Authorization refers to someone being given the right or power to carry out a particular action” - the honourable ChatGPT

Here are some more interesting citations from the OED:

1827
Authorization does away the fraud: what is authorized is legalized.
J. Bentham, Rationale of Judicial Evidence vol. V. ix.iv. v. 342

1941
I recommend authorization of construction of the St. Lawrence seaway and power project.
F. D. Roosevelt in  (1942) vol. I. 2

‍

Many character codes and carriage returns to explain one word granted, but it’s always good to drill home the meanings of certain terms especially when they’re used to describe some technical concept.

For example, it’s very easy to mistakenly conflate Authorization with Authentication (I do this all the time) when discussing access management in general.  And although this is often acceptable, it’s important to keep the distinction in mind, especially in the context of OAuth and undoubtedly when discussing Open ID Connect or OIDC.  (Did you know NetSuite can be used as an OIDC provider? That is for another episode, maybe as a closing chapter in this series).

So... Authorization Server. 

We said this is the role that generates the all important Access Token which the Client needs to retrieve the much coveted data.  The RFC defines this role as:

The server issuing access tokens to the client after successfully authenticating the resource owner and obtaining authorization.

In fact, the Authorization Server is not only responsible for issuing Access Tokens, but as you will see in a minute, it’s also involved (and preferred) in facilitating the creation of an Authorization Grant needed by the Client to obtain the access token.

With all four of the OAuth2.0 roles defined, let’s proceed to tie things all together by explaining the Protocol Flow, which is the set of interactions that must take place between the roles, for the Client to obtain an Access Token and read restricted data, which is the ultimate goal.

‍

Please refer to section 1.2 in the spec for an explanation of each of the above steps as they are extremely well explained. 

Here are the key checkpoints in this process as I see it.  These are essentially the arrows pointing left back to the Client, representing everything it needs to obtain access to resources legally.

Client gets an Authorization Grant

Client exchanges Authorization Grant for an Access Token

Client uses Access Token to read Protected Resources.

So the entire OAuth2.0 spec can be condensed into 1 phrase:

Authorization Grant -> Access Token -> Protected Resources.

If you remember nothing else from this post, remember the above.

When trying to memorize and understand these interactions, it really helps to reason things by noticing that every interaction really boils down to, 

One Role requesting something and another Role either granting/rejecting that request.

After all that is what an interaction is, reciprocal action between two or more entities.  A Call, and a Response. So the key to gaining access to protected resources is for the Client to get an authorization grant, and exchange that grant for an access token.  The authorization grant is a crucial part of this exchange.  

Here’s the full protocol flow paraphrased into a series of calls and responses:

CALL (A): The Client requests authorization from the Resource Owner.  This can be made directly to the Resource Owner, or more commonly and preferably, indirectly via the Authorization Server as an intermediary.

RESPONSE (B): The Client receives an Authorization Grant, representing the resource owner’s authorization (remember the royal message from 1855 above?).  The Authorization Grant can take the form of one of four Grant Types, depending on how the Client is requesting Authorization, and what grant types are supported by the Authorization Server.

You may be wondering, can’t we just get to the NetSuite part already?  Patience Padawans, we’re almost there.  Understanding the different Grant Types is key to understanding what options NetSuite provides for OAuth2.0. 

So the Authorization Grant is a Credential (important word, Credential). Here are the four Authorization Grant Types in OAuth2.0:

1. Authorization Code
2. Implicit
3. Resource Owner Password Credentials
4. Client Credentials

Sound familiar anyone?

https://docs.oracle.com/en/cloud/saas/netsuite/ns-online-help/section_158074210415.html

https://docs.oracle.com/en/cloud/saas/netsuite/ns-online-help/section_162730264820.html

CALL (C): The Client requests an Access Token from the Authorization Server by presenting the Authorization Grant. 

RESPONSE (D): The Authorization Server authenticates the client, validates the Authorization Grant, and if valid issues an Access Token.

FINAL CALL (E): The Client requests protected resources from the Resource Server and authenticates by presenting the Access Token.

FINAL RESPONSE (F): The Resource Server validates the Access Token, and if valid, serves the resources to the Client.

‍

Congratulations on making it through the theoretical part of this series.  Equipped with our knowledge of the Roles involved, and the protocol flow that grants the Client access to protected resources, via the issuance of an Access Token, and knowing that the Authorization Grant, which is a prerequisite for obtaining the Access Token, can be one of four types, two of which are supported by NetSuite (Authorization Code, Client Credentials), we can now finally proceed onto a practical deep dive and NetSuite OAuth tutorial for The Authorization Code Grant Flow and the Client Credentials Flow.

‍

Phew.