> 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/corppass-authorization-api-fapi-2.0/integration-guide/2.-authorization-endpoint.md). # 2. Authorization Endpoint The **Authorization Endpoint** is the entry point for the user's authentication journey. After successfully registering the request parameters via the [Pushed Authorization Request (PAR) endpoint](/technical-specifications/corppass-authorization-api-fapi-2.0/integration-guide/1.-pushed-authorization-request-par-endpoint.md), the user's browser must be redirected to this endpoint to authenticate with Corppass. ## Request (Redirect the User) To initiate the authentication session, redirect the user's browser to the Authorization Endpoint URL obtained from the [OpenID Discovery Endpoint](/technical-specifications/corppass-authorization-api-fapi-2.0/integration-guide/0.-well-known-endpoints/openid-discovery-endpoint.md) (`authorization_endpoint`). ```http GET /mga/sps/oauth/oauth20/authorize ``` ### Query Parameters Unlike legacy flows, this request does *not* contain sensitive parameters (such as `scope` or `redirect_uri`) in the query string. Instead, it utilises the `request_uri` obtained from the PAR response to reference the pre-validated payload.

Parameter Required Description

Parameter	Required	Description
`client_id`	Yes	The unique identifier assigned to the Relying Party application during onboarding. Validation: Must strictly match the `client_id` used in the preceding Pushed Authorization Request (PAR).
`request_uri`	Yes	The unique Uniform Resource Identifier (URI) that references the authorization parameters stored during the PAR step. Validation: Must be the exact `request_uri` value returned in the response from the PAR Endpoint. This URI is short-lived. The client must redirect the user to the Authorization Endpoint before the URI expires (within 60 seconds).

client_id

Yes

The unique identifier assigned to the Relying Party application during onboarding.

Validation:

Must strictly match the client_id used in the preceding Pushed Authorization Request (PAR).

request_uri

Yes

The unique Uniform Resource Identifier (URI) that references the authorization parameters stored during the PAR step.

Validation:

Must be the exact request_uri value returned in the response from the PAR Endpoint.
This URI is short-lived. The client must redirect the user to the Authorization Endpoint before the URI expires (within 60 seconds).

### Sample Request (Redirect URL) {% code overflow="wrap" %} ```http GET /mga/sps/oauth/oauth20/authorize ?client_id=51YUlwazLASM7aqMiBNW &request_uri=urn:ietf:params:oauth:request_uri:h8YQPVV0Dgm5MGaD_koAm HTTP/1.1 Host: id.corppass.gov.sg ``` {% endcode %} ## Success Response (Callback) Upon successful authentication, the user agent is redirected to the `redirect_uri` registered in the PAR step via a `302 Found` response. The following paramters are appended to the query string. ### Query Parameters

Parameter Description

Parameter	Description
`code`	Authorization Code. A short-lived, single-use credential required to retrieve Access Token and ID Token at the Token Endpoint. The code is valid for 60 seconds and can only be used once.
`state`	The opaque value originally provided by the client in the authorization request (PAR), returned unmodified. This is to mitigate Cross-Site Request Forgery (CSRF, XSRF) attacks. Validation: The Relying Party must verify that this value strictly matches the `state` stored in the user's session from the initial request (PAR). If the values do not match, the response is invalid and likely part of a Cross-Site Request Forgery (CSRF) attack. Reject the request immediately.
`iss`	The issuer identifier of the Corppass authorization server (See the `issuer` field in the OpenID Discovery Endpoint). Both success and failure response redirects will contain this parameter. For security, it is recommended that clients verify this value against the expected Corppass issuer before acting on the response. If you are using an OpenID/OAuth2 client, this will be validated by the library for you.

code

Authorization Code. A short-lived, single-use credential required to retrieve Access Token and ID Token at the Token Endpoint.

The code is valid for 60 seconds and can only be used once.

state

The opaque value originally provided by the client in the authorization request (PAR), returned unmodified. This is to mitigate Cross-Site Request Forgery (CSRF, XSRF) attacks.

Validation:

The Relying Party must verify that this value strictly matches the state stored in the user's session from the initial request (PAR).
If the values do not match, the response is invalid and likely part of a Cross-Site Request Forgery (CSRF) attack. Reject the request immediately.

iss The issuer identifier of the Corppass authorization server (See the issuer field in the OpenID Discovery Endpoint). Both success and failure response redirects will contain this parameter. For security, it is recommended that clients verify this value against the expected Corppass issuer before acting on the response. If you are using an OpenID/OAuth2 client, this will be validated by the library for you.

{% hint style="warning" %} **It is strongly recommended** to use a [certified OIDC Relying Party library](https://openid.net/developers/certified-openid-connect-implementations/), as the standard checks are automatically handled by the library. {% endhint %} ### Sample Reponse (Callback URL) ```http HTTP/1.1 302 Found Location: https://client.example.org/callback ?code=KxygiAyIIHu4OCCqjF9XAxpCjKk0uUkKNA6mfVD9HZw &state=5de6a954-a762-4975-a8f4-b692cc35b964 &iss=https%3A%2F%2Fid.corppass.gov.sg ``` ## Error Response (Callback) If authentication fails, is denied by the user, or a processing error occurs, the user agent is redirected to the `redirect_uri` (provided in the PAR step), where applicable, with the following error parameters appended to the query string. {% hint style="warning" %} Clients **must** handle the error parameters to provide appropriate feedback or guidance to the user, to ensure smooth user experience. {% endhint %} ### Query Parameters

Query Parameter	Description
`error`	A standardised error code identifying the type of error that occurred. See Error Codes below for a complete list of possible values.
`error_description`	A human-readable text description providing additional details about the error.
`state`	The opaque value originally provided by the client in the authorization request (PAR), returned unmodified if available. Validation: Used to correlate the error response with the correct user session.
`iss`	The issuer identifier of the Corppass authorization server (See the `issuer` field in the OpenID Discovery Endpoint). Both success and failure response redirects will contain this parameter. For security, it is recommended that clients verify this value against the expected Corppass issuer before acting on the response.

#### Error Codes

Error Code	Description
login_required	The user does not have an active session, the session has expired, or the session has been invalidated.
access_denied	The resource owner or authorization server denied the request.
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.

### Sample Response (Callback URL)

HTTP/1.1 302 Found
Location: https://client.example.org/callback
?error=server_error
&error_description=The+server+encountered+an+unexpected+internal+error+while+processing+the+request.
&state=Zw_r_a2uBDoy-kR7562RjM4-C9K3C2zDRQg-AJsDwb4
&iss=https%3A%2F%2Fid.corppass.gov.sg

## Next Steps **Exchange the Code for Tokens:** Once the Authorization Code is received, exchange it for the Access Token and ID Token via a secure back-channel call. **Proceed to** [**3. Token Endpoint**](/technical-specifications/corppass-authorization-api-fapi-2.0/integration-guide/3.-token-endpoint.md) **to perform the token exchange.**