Authorization Endpoint
The Authorization Endpoint is the entry point that begins the authentication flow, redirecting the user to authenticate and authorize access requested by the client application.
As Corppass requires the use of Pushed Authorization Request (PAR) as defined in RFC 9126, the Relying Party (RP) will need to perform the following steps:
Send a back-channel POST request to the
pushed_authorization_request_endpointdefined in our authorization server's OpenID configuration.Construct the authorization URL, and redirect the user to this URL.
Step 1: Sending the Pushed Authorization Request
The Pushed Authorization Request (PAR) flow is an extension of the OIDC authorization code flow that improves security.
It allows the RP to send sensitive authorization request parameters to Corppass via a back-channel, rather than exposing them in the front-channel (browser). This reduces the risk of leaking sensitive data such as scope and redirect_uri.
Request
POST /requestExample
POST /request
Content-Type: application/x-www-form-urlencoded
DPoP: <signed-DPoP-JWT>
client_id=51YUlwazLASM7aqMiBNW
&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%20authinfo
&state=5de6a954-a762-4975-a8f4-b692cc35b964
&nonce=4a0bb161-e3bb-4a56-9d75-ebea5de7a32c
&code_challenge=VQbq2FQzvY12kTkE-FoLmGHim5W7LRknTNYTUKuCKcE
&code_challenge_method=S256
&authentication_context_type=APP_AUTHENTICATION_DEFAULT
&authentication_context_message=login%20as%20corporate%20user
&acr_values=urn:singpass:authentication:loa:2
&dpop_jkt=boPCS...Request Headers
Content-Type
Yes
Must be set to application/x-www-form-urlencoded for POST requests. Indicates the encoding format of the request body.
DPoP
Yes
The JWK Thumbprint of your proof-of-possession public key. The JWK thumbprint should be computed using the SHA256 hash algorithm, and encoded using base64url.
Optional if you provide the DPoP Proof JWK in the dpop_jkt request parameter (see Request Body section below). If both are provided, they must match.
For simplicity, we recommend sending the DPoP header over the use of dpop_jkt request parameter, as the DPoP header is mandatory for later steps.
Refer to the Demonstrating Proof of Possession section for more details.
Request Body
redirect_uri
Yes
The URL that Corppass will redirect the user to after authentication. The value must match one of the redirect URLs that were pre-registered with Corppass during onboarding.
scope
Yes
A space-delimited list of scopes.
This determines the data that is returned in the ID token and in the userinfo endpoint. For more information, please refer to the Scopes section.
Must include at least openid scope.
Unrecognized or unauthorized scopes will result in an error.
response_type
Yes
The authorization processing flow to use.
Only code is supported, as mandated by FAPI2.0 specifications.
client_id
Yes
The client identifier assigned to the RP during onboarding with Corppass.
client_assertion_type
Yes
The type of client assertion.
Must be set to urn:ietf:params:oauth:client-assertion-type:jwt-bearer, as mandated by OIDC specifications.
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. It helps mitigate Cross-Site Request Forgery (CSRF, XSRF) attacks.
This value should be unique, non-guessable, and generated for each authorization session.
The value is returned in the authorization response. The RP must validate that the returned state matches the value originally provided.
nonce
Yes
A client-provided value used to mitigate replay attacks.
This value should be unique, non-guessable, and generated for each authorization session.
The value is returned in the ID Token. The RP must validate that the returned nonce matches the value originally provided.
code_challenge
Yes
The encoded and hashed value of the client-generated code_verifier.
Refer to Proof Key of Code Exchange for more details.
code_challenge_method
Yes
The method used to generate the code_challenge from the code_verifier.
Only S256 is supported, as mandated by FAPI 2.0 specifications.
acr_values
Yes
A space-delimited string indicating desired level of assurance (LoA) for the authentication.
If multiple values are provided, they should be listed in descending order of preference. The authorization server will use the first supported / available value.
The values must provided in the format
urn:singpass:authentication:loa:<number> where the number indicates the level of assurance.
Corppass currently only supports 1 possible value:
urn:singpass:authentication:loa:2- 2FA required.
More value types will be introduced in the future.
dpop_jkt
No
The JWK Thumbprint of your proof-of-possession public key. The JWK thumbprint should be computed using the SHA256 hash algorithm, and encoded using base64url.
Optional if DPoP header is provided. If both are provided, they must match.
For simplicity, we recommend sending the DPoP header over the use of dpop_jkt request parameter, as the DPoP header is mandatory for later steps.
Refer to the Demonstrating Proof of Possession section for more details.
authentication_context_type
Yes
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. Refer to the Authentication Context Parameters section for more details.
authentication_context_message
No
A string value providing context on what users are performing authentication for. This will be displayed to users during authentication.
Success Response
Response Example
Response Structure
request_uri
String
Reference to the authorization request payload sent in this request.
expires_in
Numeric
The lifetime of the request_uri in seconds. We set this value to be 60 seconds.
Error Response
Response Example
Response Structure
error
String
The error code identifying the type of error. The possible values are detailed below.
error_description
String
A human-readable description of the error.
state
String
The same state parameter value provided by the client in the pushed authorization request, returned as-is.
Error Codes
invalid_request
400
The request is missing a required parameter, includes an unsupported value, or is malformed.
invalid_client
400 / 401
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.
invalid_dpop_proof
401
The DPoP proof is invalid, expired, malformed, or failed verification.
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: Redirecting the User to the Authorization URL
After RPs complete the pushed authorization request, the next step is to redirect the user to open the authorization URL in their browser.
Instead of appending the full set of request parameters in the authorization URL, RPs only need to include two query parameters as detailed below.
Request
Request Example
client_id
Yes
The client identifier assigned to the RP during onboarding with Corppass.
This must match the client_id value provided in the request body of the pushed authorization request (Step 1).
request_uri
Yes
The request_uri value returned in the response of the pushed authorization request (Step 1).
Success Response
If the above request is successfully validated by Corppass, the user will be redirected to the Singpass login page to perform authentication.
Response Example
Step 3: Receiving the Authorization Response (after user authentication)
Upon successful authentication, the user is redirected to the RP's redirect_uri via a 302 redirect. The URL contains two key query parameters as detailed below.
Success Response
Response Example
Response Structure
code
One-time authorization code to be used by the RP to obtain the user's ID token and access token via the Token Endpoint. The code is valid for 60 seconds and cannot be used for token exchange once expired.
state
The same state parameter value provided by the client in the pushed authorization request (Step 1), returned as-is to mitigate Cross-Site Request Forgery (CSRF, XSRF) attacks.
The RP must validate that the returned state matches the value originally provided.
Validation Steps
Corppass strongly recommends that clients use a certified OIDC Relying Party library, as these standard checks will be automatically performed by the library.
Upon receiving the code and state values, clients must validate that the state value matches the value originally sent in the pushed authorization request (Step 1).
Error Response
If an error occurs after authentication, the user will be redirected to the RP's redirect_uri with the error parameters detailed below. This allows clients to obtain more context about the user's login journey.
Clients must handle the following error query parameters on the callback URL to ensure a smooth user experience.
Response Example
Response Structure
error
The error code identifying the type of error. The possible values are detailed below.
error_description
A human-readable description of the error.
state
The same state parameter value provided by the client in the pushed authorization request (Step 1), returned as-is.
Error Codes
invalid_request
The request is missing a required parameter, includes invalid or unsupported values, or is otherwise malformed.
Examples:
Missing or unrecognized
client_idclient_iddoes not match the client associated with the referencedrequest_uriInvalid client JWKS URL or invalid values being returned by the URL
invalid_request_uri
The request_uri parameter provided was missing, malformed, expired, or does not match the client associated with the referenced request_uri.
server_error
The authorization server encountered an unexpected internal error while processing the request. The error can potentially be due to the RP’s JWK endpoint being unreachable or returning a malformed JWK.
temporarily_unavailable
The server is temporarily unable to handle the request due to maintenance or high load.
Last updated