Authorization Code Grant with PKCE | Rightbrain

OAuth 2.0 Authorization Code Grant with PKCE

PKCE (Proof Key for Code Exchange, pronounced “pixie”) is an extension to the Authorization Code flow that enhances security by mitigating authorization code interception attacks. It’s highly recommended for public clients – applications like Single Page Applications (SPAs) or mobile apps that cannot securely store a Client Secret. It can also be used by confidential clients for added security.

Use Case: SPAs, mobile apps, desktop apps, or any client that cannot guarantee the confidentiality of a Client Secret.

Prerequisites:

You have registered your application in the Rightbrain dashboard.
You have obtained a Client ID.
You have registered one or more Redirect URIs for your application in the dashboard.
Your application can generate a cryptographically random string (code verifier) and derive a SHA-256 hash (code challenge) from it.

Generate Code Verifier and Challenge

Before starting the flow, your application generates a high-entropy cryptographic random string called the code_verifier (between 43 and 128 characters, using A-Z, a-z, 0-9, -, ., _, ~).
Your application then creates a code_challenge by BASE64URL-encoding the SHA-256 hash of the code_verifier.
Store Code Verifier
You must store the generated code_verifier securely (e.g., in session storage or memory) as it will be needed in Step 5 to exchange the authorization code for tokens.

Initiate Authorization Request

Redirect the user’s browser to the Rightbrain Authorization Endpoint.
Method: GET
URL: https://oauth.rightbrain.ai/oauth2/auth
Query Parameters:
- response_type=code: Specifies the desired flow.
- client_id=<YOUR_CLIENT_ID>: Your application’s Client ID.
- redirect_uri=<YOUR_REGISTERED_REDIRECT_URI>: The URL where Rightbrain will redirect the user back.
- state=<OPAQUE_VALUE>: (Recommended) A random string to prevent CSRF attacks.
- code_challenge=<GENERATED_CODE_CHALLENGE>: The BASE64URL-encoded SHA-256 hash of the code verifier (from Step 1).
- code_challenge_method=S256: Specifies the hashing method used (Rightbrain requires S256).
- scope=<SCOPES>: (Optional) A space-separated list of permissions.
  Refresh Tokens
  To receive a refresh token, you must include the offline_access scope.

Example URL (formatted for readability):

https://oauth.rightbrain.ai/oauth2/auth?
response_type=code&
client_id=YOUR_CLIENT_ID&
redirect_uri=https%3A%2F%2Fyour-app.com%2Fcallback&
state=xyzABC123&
scope=offline_access&
code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGxEaFeXBQ&
code_challenge_method=S256

Example URL (URL-encoded):

https://oauth.rightbrain.ai/oauth2/auth?response_type=code&client_id=YOUR_CLIENT_ID&redirect_uri=https%3A%2F%2Fyour-app.com%2Fcallback&state=xyzABC123&scope=offline_access&code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGxEaFeXBQ&code_challenge_method=S256

User Authorizes Application

Same as the standard Authorization Code flow (user logs in and grants consent).

Receive Authorization Code

Same as the standard Authorization Code flow (Rightbrain redirects to your redirect_uri with code and state).
Verify State Parameter
Your application must verify that the received state value matches the one stored from Step 2 to prevent Cross-Site Request Forgery (CSRF) attacks.

Exchange Code for Tokens

Your application makes a POST request to the Rightbrain Token Endpoint.
Method: POST
URL: https://oauth.rightbrain.ai/oauth2/token
Headers:
- Content-Type: application/x-www-form-urlencoded
Body (Form Data):
- grant_type=authorization_code: Specifies the grant type.
- code=<AUTHORIZATION_CODE>: The code received in step 4.
- redirect_uri=<YOUR_REGISTERED_REDIRECT_URI>: The same redirect URI used in step 2.
- client_id=<YOUR_CLIENT_ID>: Your application’s Client ID.
- code_verifier=<ORIGINAL_CODE_VERIFIER>: The original plain-text code verifier generated in Step 1.
Public Clients
Note that the client_secret is NOT included in this request when using PKCE with public clients.

Example (curl):

Exchange Code for Token (PKCE)

$ CODE="<AUTHORIZATION_CODE_FROM_STEP_4>"
> CODE_VERIFIER="<CODE_VERIFIER_FROM_STEP_1>"
> REDIRECT_URI="https://your-app.com/callback"
> CLIENT_ID="YOUR_CLIENT_ID"
> 
> curl -s -X POST \
>   -H "Content-Type: application/x-www-form-urlencoded" \
>   -d "grant_type=authorization_code" \
>   -d "code=${CODE}" \
>   -d "redirect_uri=${REDIRECT_URI}" \
>   -d "client_id=${CLIENT_ID}" \
>   -d "code_verifier=${CODE_VERIFIER}" \
>   https://oauth.rightbrain.ai/oauth2/token | jq

Receive Tokens

Rightbrain verifies the code_verifier against the code_challenge sent earlier. If valid, it responds with:
- access_token: The token used to make authenticated API calls.
- token_type: Typically Bearer.
- expires_in: The lifetime of the access token in seconds.
- refresh_token: (Optional) Issued only if the offline_access scope was requested and granted.

Call the API

Use the obtained access_token in the Authorization: Bearer <access_token> header.

Token Refresh

If you received a refresh token, you can use it to get a new access token when the current one expires. Make a POST request to the token endpoint:

Make POST Request

Method: POST
URL: https://oauth.rightbrain.ai/oauth2/token
Headers:
- Content-Type: application/x-www-form-urlencoded
Body:
- grant_type=refresh_token
- refresh_token=<YOUR_REFRESH_TOKEN>
- client_id=<YOUR_CLIENT_ID>
Public Clients
Note: client_secret is NOT sent for public clients, and code_verifier is not needed for token refresh.

Example (curl):

Refresh Token (PKCE)

$ REFRESH_TOKEN="<STORED_REFRESH_TOKEN>"
> CLIENT_ID="YOUR_CLIENT_ID"
> 
> curl -s -X POST \
>   -H "Content-Type: application/x-www-form-urlencoded" \
>   -d "grant_type=refresh_token" \
>   -d "refresh_token=${REFRESH_TOKEN}" \
>   -d "client_id=${CLIENT_ID}" \
>   https://oauth.rightbrain.ai/oauth2/token | jq

Receive New Tokens

The response will contain a new access_token and potentially a new refresh_token.