Authorization Endpoint
The Authorization Endpoint (/mga/sps/oauth/oauth20/authorize) is the entry point where the user is redirected to authenticate and authorize access requested by the client application.
This step initiates the user-facing portion of the OpenID Connect (OIDC) Authorization Code Flow and results in the issuance of an authorization code, which can later be exchanged for tokens.
Pushed Authorization Requests (PAR)
The Pushed Authorization Request (PAR) flow is an extension of the OpenID Connect (OIDC) authorization code flow that improves security. It allows the Relying Party (RP) to send sensitive authorization request parameters to Corppass via a back-channel (POST /request), rather than exposing them in the front-channel (browser).
This section outlines the steps and endpoints required to perform the PAR flow with Corppass.
Step 1: Send Authorization Request Parameters Securely
POST /requestThis endpoint allows the RP to send authorization request parameters directly to Corppass over a secure server-to-server connection. Corppass validates the request and returns a request_uri, which is a reference to the pre-registered request.
This step reduces the risk of leaking sensitive data such as scope and redirect_uri by avoiding front-channel exposure.
Request
PAR Request Example
POST /request
Content-Type: application/x-www-form-urlencoded
DPoP: <signed-DPoP-JWT>
client_id=your-client-id
&client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer
&client_assertion=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6IjEyMzQifQ...
&response_type=code
&redirect_uri=https%3A%2F%2Fclient.example.org%2Fcallback
&scope=openid
&state=sDf83sdfKJ29
&nonce=gfjs92jfslf
&code_challenge=VQbq2FQzvY12kTkE-FoLmGHim5W7LRknTNYTUKuCKcE
&code_challenge_method=S256
&dpop_jkt=boPCS...Request Headers
Content-Type
Y
Must be set to application/x-www-form-urlencoded for POST requests. Indicates the encoding format of the request body.
DPoP
N
A signed proof-of-possession JWT for binding the access token. Refer to the Demonstrating Proof of Possession section for more details.
Request Body
redirect_uri
Yes
The redirect URI used in the current authentication session
scope
Yes
Must contain at least the openid scope. For a comprehensive list of valid scopes, please refer to the Scopes section.
Unrecognized or unauthorized scopes will result in an error.
response_type
Yes
Specifies the response processing flow. Currently, Corppass only supports code as a valid value.
client_assertion_type
Yes
Must be set to urn:ietf:params:oauth:client-assertion-type:jwt-bearer
client_assertion
Yes
A JWT identifying the client. Refer to Client Assertion JWT section for more details.
state
Yes
A client-provided value used to maintain state between the request and the callback. Helps to mitigate Cross-Site Request Forgery (CSRF, XSRF) attacks.
nonce
Yes
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.
client_id
Yes
The client identifier assigned to the Relying Party during onboarding with Corppass.
code_challenge
Yes
The hashed value generated from the code verifier. Refer to Proof Key of Code Exchange for more details.
code_challenge_method
Yes
The code verifier transformation method. Currently, Corppass only supports S256 as a valid value.
dpop_jkt
Yes
The SHA-256 JWK thumbprint of the proof-of-possession public key, derived from the public key used to sign the DPoP proof for the Token Endpoint.
Response
Successful Response Example
{
"expires_in": 60,
"request_uri": "urn:ietf:params:oauth:request_uri:h8YQPVV0Dgm5MGaD_koAm"
}expires_in
Numeric
The remaining lifetime of the access token in seconds.
request_uri
String
A reference to the pre-registered authorization request.
Error Response
An example of an error response
{
"error": "invalid_request",
"error_description":"The redirect_uri is not valid for the given client"
}invalid_request
400
The request is missing a required parameter, includes an unsupported value, or is malformed.
invalid_client
400
Client authentication failed due to a missing, invalid, expired, or improperly formatted client credential or assertion.
invalid_scope
400
The requested scope is invalid, unknown, malformed, or exceeds the scope granted to the client.
server_error
500
The authorization server encountered an unexpected internal error while processing the request.
temporarily_unavailable
503
The server is temporarily unable to handle the request due to maintenance or high load.
Step 2: Redirect User to Authenticate
GET /mga/sps/oauth/oauth20/authorize This endpoint initiates the user's authentication flow. Instead of sending the full set of request parameters in the URL, the RP includes only the request_uri obtained from the /request endpoint.
Corppass retrieves the pre-validated request using the request_uri and proceeds to authenticate the user with Singpass.
Request
Request Example
GET /mga/sps/oauth/oauth20/authorize?client_id=abc123&request_uri=urn:ietf:params:oauth:request_uri:h8YQPVV0Dgm5MGaD_koAm HTTP/1.1
Host: corppass.gov.sgclient_id
Yes
The client identifier assigned to the Relying Party during onboarding with Corppass.
request_uri
Yes
A reference to the pre-registered authorization request. This reference is issued during /request call.
Response
Successful Response Example
HTTP/1.1 302 Found
Location: https://id.singpass.gov.sg/mga/sps/oauth/oauth20?client_id=...Step 3: Authorization Response (After User Authenticates)
Upon successful authentication with Singpass, Corppass issues an authorization code via a 302 Redirect to the RP’s redirect_uri.
Response
Successful Response Example
HTTP/1.1 302 Found
Location: https://client.example.org/cb?code=SplxlOBeZQQYbYS6WxSbIA&state=af0ifjsldkjcode
The authorization code returned by the authorization server in the callback URL. This one-time code must be used by the Relying Party to invoke the token endpoint and retrieve the user's ID token and access token.
state
The state parameter returned as-is to help the client maintain state between the request and the callback. It is typically employed to mitigate Cross-Site Request Forgery (CSRF, XSRF) attacks.
The authorization code issued by the authorization server has a validity period of 10 minutes. The client must exchange it for an ID token and access token within this timeframe; otherwise, it will expire and cannot be used.
Error
An example of an error response
HTTP/1.1 302 Found
Location: https://client.example.org/cb?error=invalid_request_uri&error_description=The%20request_uri%20is%20invalid%2C%20expired%2C%20malformed%2C%20or%20was%20not%20issued%20by%20the%20authorization%20server.&state=xyzinvalid_request
The client_id is missing, unrecognized, or does not match the client associated with the referenced request_uri.
invalid_request_uri
The request_uri is missing, malformed, expired, or cannot be resolved.
server_error
The authorization server encountered an unexpected internal error while processing the request.
temporarily_unavailable
The server is temporarily unable to handle the request due to maintenance or high load.
Last updated