> For the complete documentation index, see [llms.txt](https://docs.corppass.gov.sg/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.corppass.gov.sg/technical-specifications/technical-concepts/proof-key-of-code-exchange-pkce.md).

# Proof Key of Code Exchange (PKCE)

PKCE ([RFC 7636](https://datatracker.ietf.org/doc/html/rfc7636)) enhances the security of the OAuth 2.0 Authorization Code Flow by protecting against authorization code interception attacks. It is particularly important for **public clients** (e.g., mobile apps, single-page apps) that cannot securely store a client secret.

## PKCE Flow in Corppass

Corppass supports PKCE as part of the **Authorization Code Flow**, requiring the client to send a **code challenge** during the authorization request and later verify it with a **code verifier** when exchanging the authorization code for tokens.

### How PKCE Works

#### **Step 1: Client Generates a Code Verifier**

The client generates a **high-entropy random string** between 43–128 characters for each authentication request.

> Example:\
> `6I9tQd5tKn7Uy9ZfwEqd-YC71gSVfzcfVcyXLc34vQo`

#### Step 2: **Client Derives a Code Challenge**

The code verifier is hashed using **SHA-256** and then Base64URL-encoded to produce the **code challenge**.

> Example (Base64URL of SHA-256 hash):\
> `hu0mAmPq8n91vRqudsGmriiG7blJDJS0bsDeOmEt17M`

#### Step 3: Client Sends Authorization Request with Code Challenge (via PAR)

The client initiates a **Pushed Authorization Request (PAR)** to the `/request` endpoint, including the following in the request body:

```http
POST /request

response_type=code
client_id=abc123
....
code_challenge=hu0mAmPq8n91vRqudsGmriiG7blJDJS0bsDeOmEt17M
code_challenge_method=S256
```

#### Step 4: **Redirect User to Authorization Endpoint with `request_uri`**

After receiving the `request_uri` from `/request`, the client must redirect the user to the `/authorize` endpoint, passing both `client_id` and `request_uri` as query parameters.

> Example:
>
> /mga/sps/oauth/oauth20/authorize?...\&client\_id=abc123\&request\_uri=urn:ietf:params:oauth:request\_uri:h8YQPVV0Dgm5MGaD\_koAm

#### Step 5: Authorization Server Responds

Corppass responds with an **authorization code** upon successful user authentication.

#### Step 6: Client Sends Token Request with Code Verifier

The client exchanges the authorization code for an **ID token** and **access token**, providing the **original code\_verifier** to prove it generated the code challenge.

> Example:
>
> `client_id=xyz&...&code_verifier=6I9tQd5tKn7Uy9ZfwEqd-YC71gSVfzcfVcyXLc34vQo`

#### Step 7: Authorization Server Verifies Code Verifier

Corppass recomputes the `code_challenge` from the received `code_verifier` and compares it to the original challenge sent in the authorization request. If they match, the token request succeeds and tokens are issued.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.corppass.gov.sg/technical-specifications/technical-concepts/proof-key-of-code-exchange-pkce.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.