OAuth 2.0 for NetSuite - Part Three - PKCE

In parts One & Two of the OAuth2.0 for NetSuite series, we discussed the background to OAuth, the different Roles involved, and the protocol flow, which is essentially the series of interactions that must take place, for a Client to obtain an Access Token, that it could use to access protected resources in some End-User’s account.  We will assume you have read the previous articles.

Part 2 ended by saying that the theoretical part of the series was over, but well, here we go again.  A brief interlude to discuss an important and very much relevant topic is first necessary.  And that is PKCE (pronounced “Pixy”).

And before I lose you, let me just say this.

Any Client using the mcp scope must implement PKCE.  This goes for the officially supported Claude/ChatGPT clients, as well as any other currently requiring a custom integration like Perplexity and CoPilot Studio.   

There, I now have your attention.

Previously, we broke down the essence of OAuth 2.0 to the following 2 important steps:

• Client receiving Authorization Grant
• Client receiving Access Token.

The diagram below demonstrates this:

The diagram above actually depicts the Authorization Code Grant Flow (which we will deep dive into in the next part of this series).  Spoiler alert, the Authorization Code Grant Flow goes something like this:

• Client sends User to NetSuite to give their Consent and Authorize the Client to access their account
• NetSuite produces an Authorization Code representing the User’s authorization and sends (redirects) the User back to the Client with this code.
• The Client then separately approaches NetSuite with the Authorization Code, and exchanges it for an Access Token
• The Client can then access the User’s account using the Access Token.

For now just know that this way of brokering Access Tokens for the Client is susceptible to a host of attacks.  And primarily it’s Public Clients which are the most vulnerable.

So what is a Public Client?

Public vs Confidential Clients

The OAuth 2.0 spec distinguishes Public Clients from Confidential Clients, based on their ability to maintain confidentiality of their client credentials.  As you may know, every Client Application has a Client Id and a Client Secret assigned which uniquley identify it.

Confidentiality of a Client’s credentials remaining intact means that the Client could be trusted whenever some transaction requires that it must authenticate itself, such as, when acquiring Access Tokens.

Ultimately you could say:

• Public clients - cannot be trusted
• Confidential clients - trust (but verify).

Some examples of Public Clients that cannot protect the Client Secret:

• SuiteCloud SDK (native application)
• Browser-Based web apps / SPAs
• Postman
• Claude 

Confidential clients on the other hand, are all Clients which can protect their secret, typically implemented on a secure server and running in trusted infrastructure.  

These tend to be Client Applications your company owns and has built.

So, now we know Public Clients cannot be trusted, and are also susceptible to certain kinds of attacks when facilitating Client Access under OAuth 2.0

Without going into too much detail about the exact attacks (look into Authorization Code Interception, Authorization Code Injection if you’re curious), for now just know that due to the fact that the Authorization Code and Access Tokens are awarded in two separate steps, there is a window of opportunity for attackers to hijack the process.

So between steps A and D in Figure 1 above, attackers may insert themselves into the process to either obtain legitimate Access Tokens for the User’s account, or to force the User to interact with accounts that the attacker owns.

We need a way to ensure that even if an attacker were to somehow manage to hijack the session, and approach the Server (say NetSuite in this case) claiming that it has been authorized to access some user’s account, then NetSuite would not fall for it.

More specifically:

‍

Since an Authorization Code is only issued by the Server once a User explicitly gives their consent for a known Client, and

Since any Client can exchange an Authorization Code for an Access Token at the Server, 

Then we need a way for the Client to Prove that the Authorization Code it’s presenting for token exchange was legitimately obtained.

And this is exactly what Proof Key for Code Exchange (PKCE) accomplishes.

We’ll go into all the juicy details in the next part, but from a high level here is how it works.

‍

Before sending the User to NetSuite to authorize the Client, it (the Client) generates a cryptographically random value, and hashes it using SHA256.  It then passes the hashed value to the Server upon redirecting the User to give consent.  The server then generates an Authorization code, and associates the code with this hash. 

Later, when the Client goes back to the server to exchange the Authorization Code for an Access Token, the Client also presents the original (unhashed) value.  Since the Server now has:

1. the hashed value from Step 1
2. and the original value from Step 2, 

it can verify that the Authorization Code was indeed meant for this Client, by transforming the original value using the same method (SHA256), and comparing the resultant hash, to the hash it received originally in Step 1.  If these match, an Access Token is issued. Otherwise, the request is denied.

‍

This Proof of Possession works because SHA256 is a one-way function.  Meaning that once you compute the hash on the original value, there is no way to know what that original value was just by looking at the hash, even if you know what algorithm was used.  This is why we send the hashed value in Step 1.  Because later on, when a Client approaches the server and presents the original value, whose hash using the same algorithm matches identically the one received in Step 1, then the server knows it could only be the exact same Client for whom the Authorization Code was rightfully issued, that is now exchanging the code for access.  The server proves that the Client is in possession of the original value.

‍

So there we have it.  You hopefully know why PKCE is needed.  But, there’s one last thing.

PKCE has been in existence since 2015.  The NetSuite documentation on Authorization Code Grant Flow states that the use of PKCE is optional, except in a couple of cases.  

So what gives?

PKCE is here, but I’ve also heard PKCE is coming. And then while most of us only just finished implementing OAuth 2.0 (and some of us only just writing deep dives on it for NetSuite), I’m also hearing something about OAuth 2.1

OAuth 2.0 must be watching the unfolding OAuth 2.1 drama, and feeling the same way all Developers are at the moment...

And here I am spending hours writing an in-depth review of everything you need to know about OAuth 2.0 for NetSuite, knowing full well that ChatGPT can crank out a 20 page version of the same thing in less than the time it takes to say “Proof Key for Code Exchange”.  

Living the dream.

In the next post, we tie everything we have learned so far about OAuth 2.0 together, and we go deep into the Authorization Code Grant Flow, and what this looks like using concrete NetSuite examples.