### Userinfo Endpoint GET Request Example

Source: https://docs.corppass.gov.sg/technical-specifications/corppass-authorization-api-v2/endpoints/userinfo-endpoint

Example of a GET request to the Userinfo Endpoint. It requires 'Authorization' and 'DPoP' headers with the Access Token and a signed DPoP proof JWT, respectively. The DPoP proof must include the 'ath' claim.

```http
GET /userinfo HTTP/1.1
Authorization: DPoP eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
DPoP: <signed-dpop-proof-jwt>
```

--------------------------------

### Corppass API Discovery Response Example (HTTP)

Source: https://docs.corppass.gov.sg/technical-specifications/corppass-authorization-api/well-known-endpoints/openid-discovery-endpoint

An example of a successful HTTP response from the Corppass API's discovery endpoint. This response provides configuration details for OpenID Connect and OAuth 2.0 flows.

```http
HTTP/2 200
content-type: application/json; charset=utf-8
content-length: 1667  

{
  "authorization_endpoint": "https://stg-id.corppass.gov.sg/mga/sps/oauth/oauth20/authorize",
  "claims_parameter_supported": false,
  "claims_supported": [
    "nonce",
    "aud",
    "iss",
    "sub",
    "exp",
    "iat",
    "userInfo",
    "entityInfo",
    "AuthInfo",
    "TPAuthInfo",
    "rt_hash",
    "at_hash",
    "amr",
    "email",
    "email_verified",
    "sid",
    "auth_time",
    "EntityInfo"
  ],
  "code_challenge_methods_supported": [
    "S256"
  ],
  "grant_types_supported": [
    "authorization_code"
  ],
  "issuer": "https://stg-id.corppass.gov.sg",
  "jwks_uri": "https://stg-id.corppass.gov.sg/.well-known/keys",
  "authorization_response_iss_parameter_supported": false,
  "response_modes_supported": [
    "form_post",
    "fragment",
    "query"
  ],
  "response_types_supported": [
    "code"
  ],
  "scopes_supported": [
    "openid"
  ],
  "subject_types_supported": [
    "public"
  ],
  "token_endpoint_auth_methods_supported": [
    "private_key_jwt"
  ],
  "token_endpoint_auth_signing_alg_values_supported": [
    "ES256",
    "ES256K",
    "ES384",
    "ES512"
  ],
  "token_endpoint": "https://stg-id.corppass.gov.sg/mga/sps/oauth/oauth20/token",
  "id_token_signing_alg_values_supported": [
    "ES256"
  ],
  "id_token_encryption_alg_values_supported": [
    "ECDH-ES+A128KW",
    "ECDH-ES+A192KW",
    "ECDH-ES+A256KW"
  ],
  "id_token_encryption_enc_values_supported": [
    "A256CBC-HS512"
  ],
  "request_parameter_supported": false,
  "request_uri_parameter_supported": false,
  "userinfo_endpoint": "https://stg-id.corppass.gov.sg/authorization-info",
  "userinfo_signing_alg_values_supported": [
    "ES256"
  ],
  "userinfo_encryption_alg_values_supported": [
    "A128KW",
    "A256KW",
    "ECDH-ES",
    "RSA-OAEP",
    "RSA-OAEP-256",
    "dir"
  ],
  "userinfo_encryption_enc_values_supported": [
    "A128CBC-HS256",
    "A128GCM",
    "A256CBC-HS512",
    "A256GCM"
  ],
  "claim_types_supported": [
    "normal"
  ],
  "name": "corppass",
  "authorization-info_endpoint": "https://stg-id.corppass.gov.sg/authorization-info"
}
```

--------------------------------

### DPoP JWT Payload Structure Example

Source: https://docs.corppass.gov.sg/technical-specifications/corppass-authorization-api-v2/key-concepts/demonstrating-proof-of-possession-dpop

An example of a standard DPoP proof JWT payload, showcasing the typical claims included for authentication and authorization requests.

```json
{
  "htm": "POST",
  "htu": "https://id.corppass.gov.sg/mga/sps/oauth/oauth20/token",
  "iat": 1744184988,
  "jti": "5e6e5509-70e3-4bb7-ad30-4e176ffd3ca8",
  "ath": "hKzf0cQEXAMPLEUXxKXJvHr_F34Pp7pg6LFaP_LZ7Jw"
}
```

--------------------------------

### Token Endpoint Request Example (HTTP)

Source: https://docs.corppass.gov.sg/technical-specifications/corppass-authorization-api-v2/endpoints/token-endpoint

Example of a POST request to the Corppass Token Endpoint to exchange an authorization code for tokens. This request includes necessary headers like Content-Type and DPoP, and a URL-encoded body with parameters such as grant_type, code, redirect_uri, client_id, client_assertion_type, client_assertion, and code_verifier.

```http
POST /mga/sps/oauth/oauth20/token
Content-Type: application/x-www-form-urlencoded
DPoP: <signed-DPoP-JWT>

grant_type=authorization_code
&code=SplxlOBeZQQYbYS6WxSbIA
&redirect_uri=https%3A%2F%2Fclient.example.org%2Fcb
&client_id=51YUlwazLASM7aqMiBNW
&client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer
&client_assertion=eyJ...
&code_verifier=hJ1GZ4ekBQ-NNlc4t62KsLqWhM6p1ZpwRc1cwFtoLp
```

--------------------------------

### Example DPoP JWT Payload with 'ath' Claim

Source: https://docs.corppass.gov.sg/technical-specifications/corppass-authorization-api-v2/key-concepts/demonstrating-proof-of-possession-dpop

An example of a DPoP proof JWT payload that includes the 'ath' claim, typically required when accessing protected resource endpoints.

```json
{
  "htu": "https://id.corppass.gov.sg/authorization-info",
  "htm": "POST",
  "iat": 1712681904,
  "jti": "6ef56d85-e469-4bc3-a508-05d8f94f780e",
  "ath": "3rEbqHhURQcbfV3zM9sl1rsBzAcjT9TKqX3akHLZ9Nc"
}
```

--------------------------------

### Userinfo Endpoint POST Request Example

Source: https://docs.corppass.gov.sg/technical-specifications/corppass-authorization-api-v2/endpoints/userinfo-endpoint

Example of a POST request to the Userinfo Endpoint. It requires 'Content-Type', 'Authorization', and 'DPoP' headers. The 'Content-Type' must be 'application/x-www-form-urlencoded; charset=utf-8'. The request body is ignored.

```http
POST /userinfo HTTP/1.1
Content-Type: application/x-www-form-urlencoded; charset=utf-8
Authorization: DPoP eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
DPoP: <signed-dpop-proof-jwt>
```

--------------------------------

### HTTP Authorization Request with Scopes

Source: https://docs.corppass.gov.sg/technical-specifications/corppass-authorization-api/scopes

Example of an HTTP GET request to the authorization endpoint, demonstrating how to include multiple scopes as a space-separated string in the 'scope' parameter. This is crucial for requesting specific user claims and permissions during the OIDC flow.

```http
https://stg-id.corppass.gov.sg/mga/sps/oauth/oauth20/authorize
?client_id=example_client
&response_type=code
&scope=openid authinfo business_profile.email
&redirect_uri=https://example.com/callback
&state=xyz123
&nonce=abc456
```

--------------------------------

### GET /userinfo

Source: https://docs.corppass.gov.sg/technical-specifications/corppass-authorization-api-v2/endpoints/userinfo-endpoint

Retrieves detailed information of the authenticated user using the GET method. Requires an Access Token and DPoP proof.

```APIDOC
## GET /userinfo

### Description
Retrieves detailed information of the authenticated user. This endpoint requires an Access Token and a DPoP proof.

### Method
GET

### Endpoint
/userinfo

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```http
GET /userinfo HTTP/1.1
Authorization: DPoP eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
DPoP: <signed-dpop-proof-jwt>
```

### Response
#### Success Response (200)
The response is a JWS (JSON Web Signature) containing user information.
- **iat** (integer) - Issued At timestamp.
- **exp** (integer) - Expiration timestamp.
- **aud** (string) - Audience.
- **iss** (string) - Issuer.
- **sub** (string) - Subject (user identifier).
- **auth_info** (object) - Contains authorization details.
- **tp_auth_info** (object) - Contains tenant-specific authorization details.

#### Response Example
```json
{
  "iat": 1624086842,
  "exp": 1624087442,
  "aud": "vOIljWVrGyBMK6f31QYq",
  "iss": "https://id.corppass.gov.sg",
  "sub": "vOIljWVrGyBMK6f31QYq",
  "auth_info": { ... },
  "tp_auth_info": { ... }
}
```
```

--------------------------------

### JWS Header Example

Source: https://docs.corppass.gov.sg/technical-specifications/corppass-authorization-api/key-concepts/jws-and-jwe

An example of a JSON Web Signature (JWS) header, which contains metadata like the signing algorithm ('alg') and key identifier ('kid'). This header is crucial for verifying the signature's integrity and authenticity.

```json
{
  "alg": "ES256",
  "kid": "d591e152-886e-46cc-aa70-36a4431162a6",
  "typ": "JWT"
}
```

--------------------------------

### GET /mga/sps/oauth/oauth20/authorize

Source: https://docs.corppass.gov.sg/technical-specifications/corppass-authorization-api/authorization-endpoint/authorization-code-with-proof-key-of-code-exchange-pkce-flow

Initiates the OIDC authentication flow to obtain an authorization code. This code is then used to retrieve ID and access tokens from the token endpoint. The flow includes PKCE for enhanced security.

```APIDOC
## GET /mga/sps/oauth/oauth20/authorize

### Description
This endpoint initiates the OpenID Connect (OIDC) authentication flow and obtains an authorization code. This code can later be exchanged at the token endpoint for an ID token and an access token. It utilizes the Authorization Code flow with Proof Key of Code Exchange (PKCE) for enhanced security.

### Method
GET

### Endpoint
/mga/sps/oauth/oauth20/authorize

### Parameters
#### Query Parameters
- **scope** (string) - Required - Must contain at least the `openid` scope. Other valid scopes can be found in the Scopes Overview. Unrecognized or unauthorized scopes will result in an error.
- **response_type** (string) - Required - Specifies the response processing flow. Currently, only `code` is supported.
- **client_id** (string) - Required - The client identifier assigned to the Relying Party during onboarding.
- **redirect_uri** (string) - Required - The callback URL for receiving the authorization response. Must exactly match one of the registered callback URLs.
- **state** (string) - Required - A client-provided value used to maintain state between the request and the callback, helping to mitigate Cross-Site Request Forgery (CSRF, XSRF) attacks.
- **nonce** (string) - Required - A unique value provided by the RP that is returned in the ID Token. Used to prevent replay attacks and must be validated by the RP.
- **esrvcID** (string) - Optional - Applicable only to specific RPs authorized by Corppass. This parameter will be deprecated in a future version.
- **code_challenge** (string) - Required - The hashed value generated from the code verifier, used in PKCE.
- **code_challenge_method** (string) - Required - The code verifier transformation method. Currently, only `S256` is supported.

### Request Example
```
GET /mga/sps/oauth/oauth20/authorize?scope=openid&response_type=code&client_id=YOUR_CLIENT_ID&redirect_uri=YOUR_REDIRECT_URI&state=SOME_OPAQUE_VALUE&nonce=UNIQUE_NONCE&code_challenge=GENERATED_CODE_CHALLENGE&code_challenge_method=S256
```

### Response
#### Success Response (302 Redirect)
Upon successful authentication, the user agent is redirected to the `redirect_uri` with the following query parameters:
- **code** (string) - The authorization code returned by the authorization server. This one-time code is valid for 10 minutes and must be used to invoke the token endpoint.
- **state** (string) - The state parameter returned as-is to help the client maintain state and mitigate CSRF attacks.

#### Response Example
```
302 Redirect
Location: YOUR_REDIRECT_URI?code=AUTHORIZATION_CODE&state=SOME_OPAQUE_VALUE
```
```

--------------------------------

### DPoP Request Header Example

Source: https://docs.corppass.gov.sg/technical-specifications/corppass-authorization-api-v2/key-concepts/demonstrating-proof-of-possession-dpop

This example shows how to format the DPoP proof JWT within the 'DPoP' request header. The JWT itself is base64-encoded and includes cryptographic information to prove the client's possession of the signing private key. This header is essential for requests to Corppass endpoints like Pushed Authorization Request, Token, and Userinfo.

```http
DPoP: eyJhbGciOiJFUzI1NiIsInR5cCI6ImRwb3Arand0IiwiandrIjp7Imt0eSI6IkVDIiwieCI6IlBFZHFyLTFSemZ2QkZsazE0U085UkZSSm1uV2FGNlc3YlZPZ2Y3Wk9KUVkiLCJ5IjoieGVBeklzcjlTbmk1RWVnVE5xZHFZblg1V08yTm5wTHBOTXFHTEoxSjRDWSIsImNydiI6IlAtMjU2In19.eyJpYXQiOjE3NDQxODQ5ODgsImp0aSI6IjVlNmU1NTA5LTcwZTMtNGJiNy1hZDMwLTRlMTc2ZmZkM2NhOCIsImh0bSI6IlBPU1QiLCJodHRwIjoi4h0dHBzOi8vaWQuY29ycHBhc3MuZ292LnNnL21nYS9zcHMvc2F1dGgvb2F1dGgyMC90b2tlbiJ9.fggiYkc6lBwIKgpZDJjSA2c3_vkrxWHxJ_7WN9RMpyqjfgOCB1Cwlvdcw7AsGNF1nDsi59s8DHUHnM6a9warbA
```

--------------------------------

### GET /.well-known/openid-configuration

Source: https://docs.corppass.gov.sg/technical-specifications/corppass-authorization-api/well-known-endpoints/openid-discovery-endpoint

This endpoint provides the OpenID Connect discovery document for the CorpPass identity provider. It returns a JSON object containing metadata about the provider, including supported endpoints, scopes, claims, and other configuration details.

```APIDOC
## GET /.well-known/openid-configuration

### Description
This endpoint provides the OpenID Connect discovery document for the CorpPass identity provider. It returns a JSON object containing metadata about the provider, including supported endpoints, scopes, claims, and other configuration details.

### Method
GET

### Endpoint
`/.well-known/openid-configuration`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

### Request Example
```http
GET /.well-known/openid-configuration HTTP/1.1
Host: stg-id.corppass.gov.sg
Accept: application/json
```

### Response
#### Success Response (200)
- **issuer** (String) - The URL identifying the OpenID Provider (OP) as the issuer of tokens. Defined in RFC 7519, Section 4.1.1.
- **authorization_endpoint** (String) - The URL of the OP's OAuth 2.0 Authorization Endpoint, where users authenticate and provide consent. Refer to OpenID Connect Core 1.0, Section 3.1.2.
- **jwks_uri** (String) - The URL of the OP's JSON Web Key Set (JWKS) endpoint. Clients use this endpoint to retrieve public keys for validating token signatures. Refer to RFC 7517, Section 4.
- **response_types_supported** (Array) - JSON array containing a list of OAuth 2.0 `response_type` values that the OP supports. Defined in OAuth 2.0 Multiple Response Type Encoding Practices.
- **scopes_supported** (Array) - JSON array listing the OAuth 2.0 `scope` values that the OP supports, such as `openid`, which is mandatory for OpenID Connect flows.
- **subject_types_supported** (Array) - JSON array containing a list of Subject Identifier types that the OP supports, such as `public` or `pairwise`. Refer to OpenID Connect Core 1.0, Section 8.
- **claims_supported** (Array) - JSON array containing a list of Claim Names the OP may supply in tokens or the UserInfo response. Defined in OpenID Connect Core 1.0, Section 5.1.
- **grant_types_supported** (Array) - JSON array listing the OAuth 2.0 `grant_type` values supported by the OP, such as `authorization_code` or `refresh_token`. Refer to RFC 6749, Section 4.
- **token_endpoint** (String) - The URL of the OP's OAuth 2.0 Token Endpoint. Clients exchange an authorization code for tokens at this endpoint.
- **token_endpoint_auth_methods_supported** (Array) - JSON array listing the client authentication methods supported by the Token Endpoint, such as `private_key_jwt`. Refer to OpenID Connect Core 1.0, Section 9.
- **token_endpoint_auth_signing_alg_values_supported** (Array) - JSON array listing the signing algorithms supported by the Token Endpoint client authentication.

#### Response Example
```json
{
  "authorization_endpoint": "https://stg-id.corppass.gov.sg/mga/sps/oauth/oauth20/authorize",
  "claims_parameter_supported": false,
  "claims_supported": [
    "nonce",
    "aud",
    "iss",
    "sub",
    "exp",
    "iat",
    "userInfo",
    "entityInfo",
    "TPAuthInfo",
    "rt_hash",
    "at_hash",
    "amr",
    "email",
    "email_verified",
    "sid",
    "auth_time",
    "EntityInfo"
  ],
  "code_challenge_methods_supported": [
    "S256"
  ],
  "grant_types_supported": [
    "authorization_code"
  ],
  "issuer": "https://stg-id.corppass.gov.sg",
  "jwks_uri": "https://stg-id.corppass.gov.sg/.well-known/keys",
  "authorization_response_iss_parameter_supported": false,
  "response_modes_supported": [
    "form_post",
    "fragment",
    "query"
  ],
  "response_types_supported": [
    "code"
  ],
  "scopes_supported": [
    "openid"
  ],
  "subject_types_supported": [
    "public"
  ],
  "token_endpoint_auth_methods_supported": [
    "private_key_jwt"
  ],
  "token_endpoint_auth_signing_alg_values_supported": [
    "ES256",
    "ES256K",
    "ES384",
    "ES512"
  ],
  "token_endpoint": "https://stg-id.corppass.gov.sg/mga/sps/oauth/oauth20/token",
  "id_token_signing_alg_values_supported": [
    "ES256"
  ],
  "id_token_encryption_alg_values_supported": [
    "ECDH-ES+A128KW",
    "ECDH-ES+A192KW",
    "ECDH-ES+A256KW"
  ],
  "id_token_encryption_enc_values_supported": [
    "A256CBC-HS512"
  ],
  "request_parameter_supported": false,
  "request_uri_parameter_supported": false,
  "userinfo_endpoint": "https://stg-id.corppass.gov.sg/authorization-info",
  "userinfo_signing_alg_values_supported": [
    "ES256"
  ],
  "userinfo_encryption_alg_values_supported": [
    "A128KW",
    "A256KW",
    "ECDH-ES",
    "RSA-OAEP",
    "RSA-OAEP-256",
    "dir"
  ],
  "userinfo_encryption_enc_values_supported": [
    "A128CBC-HS256",
    "A128GCM",
    "A256CBC-HS512",
    "A256GCM"
  ],
  "claim_types_supported": [
    "normal"
  ],
  "name": "corppass",
  "authorization-info_endpoint": "https://stg-id.corppass.gov.sg/authorization-info"
}
```
```

--------------------------------

### Corppass Gov SG Configuration Details

Source: https://docs.corppass.gov.sg/technical-specifications/corppass-authorization-api/well-known-endpoints/openid-discovery-endpoint

This section details the configuration parameters and supported features of the Corppass Gov SG system, including supported algorithms for token and ID token signing/encryption, endpoint URLs, and parameter support for OpenID Connect and OAuth 2.0.

```APIDOC
## Corppass Gov SG Configuration

### Description
Provides details about the supported features, algorithms, and endpoints within the Corppass Gov SG system for identity and access management.

### Method
GET

### Endpoint
/websites/corppass_gov_sg

### Parameters
None

### Request Example
None

### Response
#### Success Response (200)
- **token_endpoint_auth_methods_supported** (Array) - JSON array listing the authentication methods supported by the Token Endpoint for JWT authentication.
- **jwks_uri** (String) - The URL for the JSON Web Key Set (JWKS), used to verify the signature of JSON Web Tokens (JWTs).
- **response_types_supported** (Array) - JSON array listing the OAuth 2.0 <code>response_type</code> values that the OP supports.
- **subject_types_supported** (Array) - JSON array listing the <code>subject_type</code> values that the OP supports.
- **id_token_signing_alg_values_supported** (Array) - JSON array listing the JWS signing algorithms (<code>alg</code> values) supported by the OP for signing ID Tokens.
- **id_token_encryption_alg_values_supported** (Array) - JSON array listing the JWE encryption algorithms (<code>alg</code> values) supported by the OP for encrypting ID Tokens.
- **id_token_encryption_enc_values_supported** (Array) - JSON array listing the JWE encryption algorithms (<code>enc</code> values) supported by the OP for encrypting ID Tokens.
- **authorization-info_endpoint** (String) - The URL of the OP's Authorization Info Endpoint, used to retrieve the user's authorization and third-party authorization details.
- **claims_parameter_supported** (Boolean) - Boolean value indicating whether the OP supports the <code>claims</code> parameter to request specific claims.
- **code_challenge_methods_supported** (Array) - JSON array listing the Proof Key for Code Exchange (PKCE) <code>code_challenge</code> methods supported by the OP.
- **authorization_response_iss_parameter_supported** (Boolean) - Boolean indicating whether the OP includes the <code>iss</code> parameter in the authorization response.
- **response_modes_supported** (Array) - JSON array listing OAuth 2.0 <code>response_mode</code> values supported by the OP.
- **request_parameter_supported** (Boolean) - Boolean indicating whether the OP supports the <code>request</code> parameter for JWT-based requests.
- **request_uri_parameter_supported** (Boolean) - Boolean indicating whether the OP supports the <code>request_uri</code> parameter.
- **claim_types_supported** (Array) - JSON array listing the Claim Types supported by the OP.
- **userinfo_endpoint** (String) - The URL of the OP's UserInfo Endpoint, used to retrieve claims about the authenticated user.
- **userinfo_signing_alg_values_supported** (Array) - JSON array listing JWS signing algorithms (<code>alg</code> values) supported by the UserInfo Endpoint for encoding claims in a JWT.
- **userinfo_encryption_alg_values_supported** (Array) - JSON array listing JWE encryption algorithms (<code>alg</code> values) supported by the UserInfo Endpoint for encrypting claims in a JWT.
- **userinfo_encryption_enc_values_supported** (Array) - JSON array listing JWE encryption algorithms (<code>enc</code> values) supported by the UserInfo Endpoint for encrypting claims in a JWT.

#### Response Example
{
  "token_endpoint_auth_methods_supported": ["private_key_jwt", "client_secret_basic"],
  "jwks_uri": "https://sandbox.corppass.gov.sg/auth/realms/mas/protocol/openid-connect/certs",
  "response_types_supported": ["code", "id_token", "code id_token"],
  "subject_types_supported": ["public"],
  "id_token_signing_alg_values_supported": ["RS256"],
  "id_token_encryption_alg_values_supported": ["RSA-OAEP"],
  "id_token_encryption_enc_values_supported": ["A128CBC-HS256", "A192CBC-HS384", "A256CBC-HS512"],
  "authorization-info_endpoint": "https://sandbox.corppass.gov.sg/auth/realms/mas/protocol/openid-connect/authz-info",
  "claims_parameter_supported": false,
  "code_challenge_methods_supported": ["S256"],
  "authorization_response_iss_parameter_supported": false,
  "response_modes_supported": ["query", "fragment"],
  "request_parameter_supported": false,
  "request_uri_parameter_supported": true,
  "claim_types_supported": ["normal"],
  "userinfo_endpoint": "https://sandbox.corppass.gov.sg/auth/realms/mas/protocol/openid-connect/userinfo",
  "userinfo_signing_alg_values_supported": ["RS256"],
  "userinfo_encryption_alg_values_supported": ["RSA-OAEP"],
  "userinfo_encryption_enc_values_supported": ["A128CBC-HS256", "A192CBC-HS384", "A256CBC-HS512"]
}
```

--------------------------------

### Example auth_info Claim Structure (JSON)

Source: https://docs.corppass.gov.sg/technical-specifications/corppass-authorization-api-v2/endpoints/userinfo-endpoint/auth-info-structure

This JSON structure represents a sample 'auth_info' claim for a user with multiple authorizations. It includes details like e-service IDs, roles, and associated parameters.

```json
{
  "auth_info": {
    "Result_Set": {
      "ESrvc_Row_Count": 2,
      "ESrvc_Result": [
        {
          "CPESrvcID": "SAMPLE-ESERVICE",
          "Auth_Result_Set": {
            "Row_Count": 1,
            "Row": [
              {
                "CPEntID_SUB": "",
                "CPRole": "Approver",
                "StartDate": "2017-11-14",
                "EndDate": "9999-12-31",
                "Parameter": [
                  {
                    "name": "Effective YA",
                    "value": "2020"
                  }
                ]
              }
            ]
          }
        },
        {
          "CPESrvcID": "OTHER-ESERVICE",
          "Auth_Result_Set": {
            "Row_Count": 1,
            "Row": [
              {
                "CPEntID_SUB": "",
                "CPRole": "Editor",
                "StartDate": "2017-11-14",
                "EndDate": "9999-12-31",
                "Parameter": []
              }
            ]
          }
        }
      ]
    }
  }
}
```

--------------------------------

### Pushed Authorization Request (PAR) with PKCE

Source: https://docs.corppass.gov.sg/technical-specifications/corppass-authorization-api-v2/key-concepts/proof-key-of-code-exchange-pkce

Initiate a Pushed Authorization Request (PAR) to the `/request` endpoint, including the code challenge and its method.

```APIDOC
## POST /request

### Description
Initiates a Pushed Authorization Request (PAR) for the OAuth 2.0 Authorization Code Flow with PKCE support.

### Method
POST

### Endpoint
`/request`

### Parameters
#### Query Parameters
None

#### Request Body
- **response_type** (string) - Required - The value MUST be `code`.
- **client_id** (string) - Required - The client identifier.
- **code_challenge** (string) - Required - The transformed code verifier.
- **code_challenge_method** (string) - Required - The method used to derive the code challenge. Supported value is `S256`.

### Request Example
```http
POST /request

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

### Response
#### Success Response (200)
- **request_uri** (string) - A URI that identifies the authorization request. This URI is short-lived and can only be used once.

#### Response Example
(Response body structure not detailed in the provided text, but would typically contain a `request_uri`)
```

--------------------------------

### Corppass Error Response Example

Source: https://docs.corppass.gov.sg/technical-specifications/corppass-authorization-api-v2/endpoints/userinfo-endpoint

An example of an error response from the Corppass API, indicating a specific error code and a human-readable description. This structure is used for various API errors, such as invalid requests or tokens.

```json
{
  "error": "invalid_request",
  "error_description": "Request is missing or malformed."
}
```

--------------------------------

### Supported Scopes Overview

Source: https://docs.corppass.gov.sg/technical-specifications/corppass-authorization-api-v2/scopes

Details on the scopes supported by Corppass, including their descriptions, the claims they provide, and relevant endpoints.

```APIDOC
## Supported Scopes

### `openid`
- **Scope Description**: Mandatory scope to indicate the request is an OpenID Connect flow. Required for all requests.
- **Claims**: `sub`, `act`, `amr`, `nonce`, `aud`, `exp`, `iat`, `iss`
- **Relevant Endpoint**: Token Endpoint

### `sub_account`
- **Scope Description**: Provides more details about the user that is acting on behalf of the entity.
- **Claims**: `act.sub_account`
- **Relevant Endpoint**: Token Endpoint

### `authinfo`
- **Scope Description**: Provides authorization details for the authenticated user. This scope must be provided or else no authorization information will be returned in the userinfo endpoint.
- **Claims**: `auth_info`
- **Relevant Endpoint**: Userinfo Endpoint

### `tpauthinfo`
- **Scope Description**: Provides third-party authorization details for the authenticated user. This scope must be provided or else no third-party authorization information will be returned in the userinfo endpoint.
- **Claims**: `tp_auth_info`
- **Relevant Endpoint**: Userinfo Endpoint

### `business_profile.email`
- **Scope Description**: Provides the email of the user that is acting on behalf of the entity, as registered on Corppass. The `sub_account` scope must be provided as well for the relevant email claims to show up.
- **Claims**: `act.sub_account.email`, `act.sub_account.email_verified`
- **Relevant Endpoint**: Token Endpoint
```

--------------------------------

### OpenID Provider Configuration Discovery

Source: https://docs.corppass.gov.sg/technical-specifications/corppass-authorization-api-v2

Retrieve the OpenID Provider configuration details by querying the OpenID Discovery endpoint. This is the first step in the OIDC flow.

```APIDOC
## GET /.well-known/openid-configuration

### Description
Retrieves the OpenID Provider's configuration document, which contains information about the issuer, authorization endpoints, token endpoints, and other discovery details.

### Method
GET

### Endpoint
`/.well-known/openid-configuration`

### Parameters
#### Query Parameters
None

### Request Example
None

### Response
#### Success Response (200)
- **jwks_uri** (string) - The URI of the JSON Web Key Set (JWKS) document.
- **authorization_endpoint** (string) - The URI of the authorization endpoint.
- **token_endpoint** (string) - The URI of the token endpoint.
- **userinfo_endpoint** (string) - The URI of the Userinfo endpoint.
- **issuer** (string) - The issuer identifier for the authorization server.

#### Response Example
```json
{
  "jwks_uri": "https://example.com/.well-known/jwks.json",
  "authorization_endpoint": "https://example.com/mga/sps/oauth/oauth20/authorize",
  "token_endpoint": "https://example.com/mga/sps/oauth/oauth20/token",
  "userinfo_endpoint": "https://example.com/mga/sps/oauth/oauth20/userinfo",
  "issuer": "https://example.com"
}
```
```

--------------------------------

### Pushed Authorization Request (PAR) Example

Source: https://docs.corppass.gov.sg/technical-specifications/corppass-authorization-api-v2/scopes

Example of how to specify scopes in a Pushed Authorization Request (PAR) using form-urlencoded data. Scopes should be provided as a space-separated list in the 'scope' parameter.

```APIDOC
## POST /request

### Description
Initiates a Pushed Authorization Request (PAR) including OpenID Connect scopes.

### Method
POST

### Endpoint
/request

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **client_id** (string) - Required - The client identifier.
- **client_assertion_type** (string) - Required - The type of client assertion, typically `urn:ietf:params:oauth:client-assertion-type:jwt-bearer`.
- **client_assertion** (string) - Required - The client assertion JWT.
- **response_type** (string) - Required - The expected response type, e.g., `code`.
- **redirect_uri** (string) - Required - The URI to redirect the user to after authorization.
- **scope** (string) - Required - A space-separated list of requested scopes (e.g., `openid authinfo business_profile.email`).
- **state** (string) - Recommended - An opaque value used to maintain state between the request and callback.
- **nonce** (string) - Required - A string value used to mitigate replay attacks.
- **code_challenge** (string) - Required - The challenge for PKCE.
- **code_challenge_method** (string) - Required - The method used for the code challenge, typically `S256`.

### Request Example
```http
POST /request
Content-Type: application/x-www-form-urlencoded
DPoP: <signed-DPoP-JWT>

client_id=...
&client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer
&client_assertion=eyJ...
&response_type=code
&redirect_uri=https%3A%2F%2Fclient.example.org%2Fcallback
&scope=openid authinfo business_profile.email
&state=sDf83sdfKJ29
&nonce=gfjs92jfslf
&code_challenge=VQbq2FQzvY12kTkE-FoLmGHim5W7LRknTNYTUKuCKcE
&code_challenge_method=S256
```

### Response
#### Success Response (200)
(Response details for PAR are typically a JSON object containing a `request_uri`)

#### Response Example
```json
{
  "request_uri": "urn:ietf:params:oauth:request_uri:e947c227-4702-414f-9f14-282c91349502"
}
```
```

--------------------------------

### Sample tp_auth_info Claim Structure

Source: https://docs.corppass.gov.sg/technical-specifications/corppass-authorization-api-v2/endpoints/userinfo-endpoint/third-party-auth-info-structure

JSON payload example showing the tp_auth_info claim structure for a user with two third-party authorizations for an e-service. Demonstrates the nested structure including e-service details, entity information, roles, and authorization dates.

```json
{
  "tp_auth_info": {
    "Result_Set": {
      "ESrvc_Row_Count": 1,
      "ESrvc_Result": [
        {
          "CPESrvcID": "SAMPLE-ESERVICE",
          "Auth_Set": {
            "ENT_ROW_COUNT": 2,
            "TP_Auth": [
              {
                "CP_Clnt_ID": "T00YY8888X",
                "CP_ClntEnt_TYPE": "UEN",
                "Auth_Result_Set": {
                  "Row_Count": 1,
                  "Row": [
                    {
                      "CP_ClntEnt_SUB": "",
                      "CPRole": "Maker",
                      "StartDate": "2025-09-05",
                      "EndDate": "9999-12-31",
                      "Parameter": []
                    }
                  ]
                }
              },
              {
                "CP_Clnt_ID": "T99BB0000A",
                "CP_ClntEnt_TYPE": "UEN",
                "Auth_Result_Set": {
                  "Row_Count": 1,
                  "Row": [
                    {
                      "CP_ClntEnt_SUB": "",
                      "CPRole": "Checker",
                      "StartDate": "2025-09-05",
                      "EndDate": "9999-12-31",
                      "Parameter": []
                    }
                  ]
                }
              }
            ]
          }
        }
      ]
    }
  }
}
```

--------------------------------

### Corppass PAR Endpoint Request Body Example (JSON)

Source: https://docs.corppass.gov.sg/technical-specifications/corppass-authorization-api/pushed-authorization-request-par-endpoint

An example of the JSON response body returned by the Corppass Pushed Authorization Request (PAR) endpoint. It includes fields like 'expires_in' and 'request_uri'.

```json
{
  "expires_in": 60,
  "request_uri": "urn:ietf:params:oauth:request_uri:h8YQPVV0Dgm5MGaD_koAm"
}
```

--------------------------------

### Authentication Context Parameters

Source: https://docs.corppass.gov.sg/technical-specifications/corppass-authorization-api-v2/endpoints/authorization-endpoint/authentication-context-parameters

Details on the new parameters for contextualizing authorization requests in Corppass.

```APIDOC
## Authentication Context Parameters

New parameters have been introduced in the authorization flow to help contextualize each authorization request. These parameters are not part of any standard OIDC specification and are specific to Corppass.

### Parameters

#### Request Body Parameters

- **authentication_context_type** (string) - Required - A value from a predefined list describing the type of transaction for which your user is performing the authentication. This is used for anti-fraud purposes.
  The list of supported values is provided below.

- **authentication_context_message** (string) - Optional - A string value providing context on what users are performing authentication for. As part of future enhancements, this value will be displayed to users during authentication. Therefore, it is advised that you provide a message that is comprehensible to your users.

### Supported Values for `authentication_context_type`

(Note: The actual list of supported values was not provided in the input text and should be added here.)

### Example Usage

(Note: A specific endpoint or example request demonstrating the use of these parameters was not provided in the input text and should be added here.)
```

--------------------------------

### Corppass Access Token JWT Payload Example

Source: https://docs.corppass.gov.sg/technical-specifications/corppass-authorization-api-v2/endpoints/token-endpoint/access-token-structure

An example of the JWT payload within a Corppass access token. While RPs should treat the token as opaque, this payload provides informational claims such as issuer, audience, expiration, and subject.

```json
{
  "iat": 1716451740,
  "exp": 1716452339,
  "iss": "https://stg-id.corppass.gov.sg",
  "scope": "authinfo tpauthinfo",
  "aud": ["https://stg-id.corppass.gov.sg/authorization-info"],
  "client_id": "97ZZnLxUfzzVz50kfCwB",
  "sub": "CP192",
  "jti": "vhC0eLzU-ol8IQ0RuFL5f",
  "cnf": {
    "jkt": "0ZcOCORZNYy-DWpqq30jZyJGHTN0d2HglBV3uiguA4I"
  }
}
```

--------------------------------

### ID Token JWS Payload Example (JSON)

Source: https://docs.corppass.gov.sg/technical-specifications/corppass-authorization-api/token-endpoint/id-token-structure

An example of the JWS payload returned by the ID Token. This JSON object contains various claims including standard OIDC claims and Corppass-specific custom claims like userInfo and entityInfo.

```json
{
    "iat": 1623162109,
    "iss": "https://stg-id.corppass.gov.sg",
    "at_hash": "6J4VlBBQpbAyy1NL4NBW-Q",
    "sub": "s=S1234567P,uuid=0f14a2fc-09c2-4780-95f0-8c28347f2780,u=CP192,c=SG",
    "exp": 1623165709,
    "aud": "vOIljWVrGyBMK6f31QYq",
    "amr": ["pwd", "sms"],
    "nonce": "ZEF+97zc3YZP7huv6nzKspfabDv0wRtce/aVNud23vU=",
    "userInfo":{
        "CPAccType": "User",
        "CPUID_FullName": "John Grisham",
        "ISSPHOLDER": "YES"
    },
    "email": "testemail@corppass.gov.sg",
    "email_verified": true,
    "entityInfo": {
        "CPEntID": "82532759L",
        "CPEnt_TYPE": "UEN",
        "CPEnt_Status": "Registered",
        "CPNonUEN_Country": "",
        "CPNonUEN_RegNo": "",
        "CPNonUEN_Name": ""
    }
}
```

--------------------------------

### DPoP JWT Header Structure Example

Source: https://docs.corppass.gov.sg/technical-specifications/corppass-authorization-api-v2/key-concepts/demonstrating-proof-of-possession-dpop

Illustrates the structure of a DPoP proof JWT header, which contains cryptographic algorithm details and the public key (jwk) used for signing. The 'typ' must be 'dpop+jwt', and 'alg' specifies the signing algorithm, with 'jwk' containing the public component of the ephemeral key pair.

```json
{
  "typ": "dpop+jwt",
  "alg": "ES256",
  "jwk": {
    "kty": "EC",
    "crv": "P-256",
    "x": "...",
    "y": "..."
  }
}
```

--------------------------------

### SFA User Sub Account Claim Example

Source: https://docs.corppass.gov.sg/technical-specifications/corppass-authorization-api-v2/endpoints/token-endpoint/id-token-structure

Provides a sample nested sub_account claim for a Singpass Foreign Account (SFA) user. This example includes account_type as 'SFA', foreign_id, foreign_id_coi (country code), name, email, and email verification status.

```json
{
  "act": {
    "sub": "1c0cee38-3a8f-4f8a-83bc-7a0e4c59d6a9",
    "sub_account": {
      "account_type": "SFA",
      "foreign_id": "K28394589",
      "foreign_id_coi": "MY",
      "name": "John Grisham",
      "email": "testemail@corppass.gov.sg",
      "email_verified": true
    }
  }
}
```