What's new in V2

If you are migrating over from Corppass Authorization API V1, here is a quick summary of all the new changes introduced in V2.

Pushed Authorization Request (PAR) Flow

For added security, it is now mandatory for all RPs to implement the PAR flow, and initiate authentication using the backchannel request, PAR.

See Authorization Endpoint for more information.

Proof Key of Code Exchange (PKCE)

For added security, it is mandatory for all RPs to implement PKCE when performing the PAR flow.

See Proof Key of Code Exchange for more information.

Demonstrating Proof of Possession (DPoP)

For added security, it is mandatory for all RPs to send a DPoP Proof JWT for

• PAR request

• Token request

• Subsequent calls to protected resource endpoints (eg. Userinfo Endpoint)

See Demonstrating Proof of Possession (DPoP) for more information.

Authorization Context Parameters

The following parameters have been introduced to help contextualize each authentication request:

• authentication_context_type (Mandatory)

• authentication_context_message (Optional)

See Authorization Endpoint - Request Body and Authentication Context Parameters for more information.

New Scopes

New scope:

• auth_info

• tp_auth_info

• sub_account

• business_profile.email

See Scopes for more information.

Changes to ID Token Structure

Changes to the following claims:

• sub claim value now be the entity's UEN (or Corppass-issued entity identifier for non-uen entities)

• New act claim

• New sub_account claim

See ID Token Structure for more information.

Changes to Authorization Info Endpoint

The Authorization Info Endpoint will be replaced by the Userinfo Endpoint. Relying parties should use the URL path as specified on Corppass OpenID Discovery Endpoint under "userinfo_endpoint" .

There are some slight tweaks to the response payload structure as well.

See Userinfo Endpoint - Response Structure for more information.

Stricter TTL requirements

• The maximum accepted client assertion lifespan is reduced from 10mins to 2mins. Read more here.

• The expiry of authorization code is reduced from 10mins to 1min.

Changes to Error Handling

Relying parties must now implement error handling logic on their callback/redirect URLs to handle new error query parameters that will be returned after failures on the Authorisation Endpoint.

See Authorization Endpoint - Error Response for more information.

(scratch version, see which one is easier to understand and keep that one)

• Pushed Authorization Request Flow is now mandatory

  • RPs must initiate auth using a PAR request (backchannel)

  • The authorisation endpoint now only accepts request_uri, the result from the PAR request

• New authorisation parameters

  • transaction_category - mandatory for Login clients, must select from a list of pre-allocated values (configure during RP onboarding)

  • auth_context_msg - optional, only allowed for Login clients. Free text fields, can be different for each transaction

• PKCE is now mandatory

• DPoP is now mandatory

  • Must generate and present DPoP token during PAR

  • Must present DPoP token when performing token exchange

  • Must present DPoP token for subsequent calls to protected endpoints

• New scopes (and claims)

  • same as prev: openid authinfo tpauthinfo

  • new: sub_account

• ID token structure change

  • sub claim

  • act claim (and structure)

  • sub_account claim

• Authorisation Info Endpoint --> replaced by Userinfo Endpoint

  • Slight tweak to response object. Top-level field names change to snake case (auth_info, tp_auth_info)

For MIB

• New scopes will be supported

  • For entity and person information

  • Depends on MyInfo Business V5 data catalogue (not confirmed now)

  • RPs to add these scopes via SDP (subject to approval)

  • Note: If a commercial/quasi-govt RP requests for any of these new MIB scopes, the user must explicitly grant consent before authentication can continue. Users will be redirected to the consent page by Corppass.

• Userinfo Endpoint will return additional attributes

  • person_info - if scopes related to "person" information is requested

  • entity_info - if scopes related to "entity" information is requested