Migration Guide: Legacy to FAPI 2.0

This guide assists partners in transitioning existing integrations from the Corppass Authorization API (Legacy) to the new FAPI 2.0‑compliant Authorization API.

The new implementation strengthens security by adopting the Financial-grade API (FAPI) 2.0 Security Profile, built on OAuth 2.0 and OpenID Connect.

Why Migrate?

FAPI 2.0 introduces enhanced security mechanisms, mandated flows, and updated token structures that improve confidentiality, integrity, and replay protection compared to the Legacy API. These changes align with global security best practices and provide long‑term reliability.

Key Changes

Overview

Feature

Legacy Security Profile

FAPI 2.0 Security Profile

Authorization Flow

Front-channel redirect (params in URL).

Pushed Authorization Request (PAR) (params sent via back-channel).

The requests are also contextualised with new parameters:

authentication_context_type
authentication_context_message

Enhanced Security

Standard Authorization Code with Bearer Tokens.

Enhanced security with

Mandatory PKCE.
Mandatory DPoP (sender-constrained tokens).
Stricter TTL requirements.

Scopes & Consent

Standard scopes (openid, authinfo, tpauthinfo)

No consent screen displayed during authorization.

Finer-grained scopes (e.g., entity.identity, user.identity, user.name), allowing for more precise data access control.

A consent screen may be displayed during authorization, depending on the requested scopes.

ID Token

Flat, custom structure.

sub encapsulating user information.
entityInfo encapsulating entity information.
userInfo encapsulating acting user's information.

Structured, hierarchical structure.

sub representing subject (entity / user) identifier.
sub_attributes encapsulating profile information related to the subject (entity on primary / root level, user on actor level).
act encapsulating information related to the subject acting on behalf of the primary subject.

Userinfo Endpoint

Endpoint: /authorization-info.

Returns PascalCase keys:

AuthInfo
TPAuthInfo

Endpoint: /userinfo (Standard OIDC endpoint name)

Returns snake_case keys:

auth_info
tp_auth_info

Error Handling

Legacy / custom error formats

Standardised OAuth 2.0 Errors.

error
error_description
state

Authorization Flow & Enhanced Security

Pushed Authorization Request (PAR) Flow

All RPs must implement the PAR flow for enhanced security.
The authorization request is initiated via the backchannel /request endpoint (PAR).
Refer to Authorization Endpoint for more details.

Proof Key of Code Exchange (PKCE)

PKCE is mandatory for all RPs performing the PAR flow for enhanced security. This provides additional protection against authorization code interception.
Refer to Proof Key of Code Exchange for more details.

Demonstrating Proof of Possession (DPoP)

A DPoP Proof JWT must be included for:
- PAR requests
- Token requests
- Subsequent calls to protected resource endpoints (e.g., Userinfo Endpoint)
Refer to Demonstrating Proof of Possession (DPoP) for more details.

Stricter TTL requirements

Maximum client assertion lifespan reduced is reduced from 10mins to 2mins. Refer to Client Assertion JWT for more details.
Authorization code expiry is reduced from 10 min to 1 min. Refer to Token Endpoint for more details.

Authentication Context Parameters

Two new parameters are introduced to support contextualizing authentication requests:
- authentication_context_type (Mandatory)
- authentication_context_message (Optional)
See Pushed Authorization Request (PAR) Endpoint and Authentication Context Parameters for more details.

New finer-grained scopes are introduced to provide more control over requested authorization:
- Authorization scopes
  - authinfo
  - tpauthinfo
- Entity scopes
  - entity.identity
  - entity.basic_profile.name
  - entity.basic_profile.uen_status
- User scopes
  - user.identity
  - user.name
  - user.corppass.email
A consent screen may be displayed to the end user during authorization, depending on the requested scopes.
Refer to Scopes for more details.

ID Token and Userinfo Changes

Changes to ID Token Structure

Adopts a nested structure for better organisation and standard alignment where possible.

sub claim value now references the subject identifier directly.
- Primary (entity) level: The entity's UEN or Corppass-issued entity identifier for non-UEN entities.
- Actor (user) level: The user's unique identifier.
New claims introduced
- sub_type
- sub_attributes - encapsulating profile information related to the subject (entity on primary level, user on actor level).
- act - encapsulating information related to the actor subject (user) acting on behalf of the primary subject (entity).
Deprecated claims
- entityInfo -> replaced by sub_attributes
- userInfo -> replaced by act.sub_attributes
- email -> replaced by act.sub_attributes.corppass_email
- email_verified -> replaced by act.sub_attributes.corppass_email_verified
Refer to ID Token for more details.

Userinfo Endpoint

The Authorization Info Endpoint (/authorization-info) is replaced by the Userinfo Endpoint (/userinfo), which is the standard OIDC endpoint name.
The userinfo_endpoint URL is provided in the Corppass OpenID Discovery document.
Minor adjustments to the response payload structure:
- AuthInfo claim -> auth_info
- TPAuthInfo claim -> tp_auth_info
Refer to Userinfo Endpoint for more details.

Error Handling

The API now returns standardized OAuth 2.0 error responses across all endpoints. This replaces legacy error formats with consistent parameters: error, error_description, and state (where available).

API Calls (Back-channel): Direct API requests (e.g., PAR, Token, Userinfo endpoints) will return these error parameters in the JSON response body with the appropriate HTTP status code.
Authorization Redirects (Front-channel): If a failure occurs during the authorization flow, the user's browser will be redirected to your redirect_uri with these parameters appended as query strings.

Your application must be updated to handle these standard error parameters for both direct API calls and callback URLs. Refer to the documentation for each endpoint for specific error responses.

Migration Steps

Step 1: Review Client Configuration & Scopes

Review your client configuration on the Corppass Developer Portal to accommodate new mandatory parameters and scope changes.

Review Authentication Context Type: FAPI 2.0 introduces authentication_context_type as a mandatory parameter to define the transaction context.
1. Configuration: Your client profile now includes a list of "Supported Authentication Context Types". Currently, only APP_AUTHENTICATION_DEFAULT is supported. This value will be automatically backfilled for all existing clients.
2. Constraint: During an authorization request, you can only request a context type that is explicitly configured for your client. For now, you must use APP_AUTHENTICATION_DEFAULT value in your requests.
Refer to the Authentication Context Parameters section for more details.
Review Scopes: FAPI 2.0 introduces new finer-grained scopes.
1. Configuration: To ensure continuity, Corppass will automatically backfill your client profile with finer-grained FAPI 2.0 scopes corresponding to your legacy access.
2. Review: Audit the backfilled scopes in your client configuration. Remove any that provides access to data your application no longer needs.
Refer to the Scopes section for more details.

Step 2: Update Keys (JWKS) & Discovery

Client Keys (JWKS):
1. Compliance: You must ensure your JWKS remains compliant with security specifications. Both Legacy and FAPI 2.0 profiles require you to publish keys for two distinct purposes:
  1. Signing Key (use: "sig"): Continue using your signing key to sign your Client Assertions and DPoP proofs.
  2. Encryption Key (use: "enc"): Requirement: Corppass encrypts ID Tokens (JWE) using this key. Verify that your JWKS contains a public key with use: "enc". If you were previously operating without one, you must generate and publish it now.
Refer to Client JWKS for more details.
Discovery URL:
The OpenID Connect Discovery URL remains the same as the Legacy API.
1. New Endpoints: Query the existing Discovery URL to retrieve updated provider metadata. Configure your application to use the new endpoint values found in the metadata:
  1. pushed_authorization_request_endpoint (New: Required for PAR)
  2. userinfo_endpoint (Replaces /authorization-info)
Refer to OpenID Discovery Endpoint for more details.

Step 3: Authorization Request

Significant Change: You can no longer construct the authorization URL directly in the browser. You need to implement Pushed Authorization Request (PAR).

Call the PAR Endpoint (/request):
1. Initiate the flow via a back-channel POST request.
2. Include DPoP proof in the request.
3. Include the necessary OIDC parameters (e.g., client_id, scope, redirect_uri) along with the new mandatory fields (e.g., client_assertion, code_challenge, authentication_context_type).
4. Corppass returns a request_uri that references your payload.
Browser Redirect to Authorization Endpoint (/authorize):
1. Redirect the user to the Authorization Endpoint using only client_id and the returned request_uri returned in the previous step.
2. This replaces the Legacy method of exposing sensitive parameters directly in the browser URL.

Refer to Pushed Authorization Request (PAR) Endpoint for more details.

Step 4: Token Exchange

The Token Endpoint (/token) now enforces strict security proofs.

Prepare the Request:
1. Mandatory Client Auth: Use client_assertion (Private Key JWT).
2. Mandatory PKCE: Include the code_verifier matching the code_challenge from PAR.
3. Mandatory DPoP: Include a DPoP HTTP header. The public key in this header will be bound to the resulting Access Token.
Handle the Response:
1. Access Token: Store the opaque token for subsequent API calls where needed.
  1. Note: The token is sender-constrained; you must use the same DPoP private key from the request to sign the DPoP header when using this token later.
2. ID Token: Decrypt the JWE using your private encryption key to retrieve the signed payload, then validate the signature. See Step 5.

Refer to Token Endpoint for more details.

Step 5: Decrypt & Map ID Token

The ID Token is an Encrypted JWT (JWE).

Decrypt: Use your private encryption key (from Step 2) to decrypt the token.
Validate: Verify the signature of the decrypted payload using Corppass's public signing key.
Map New Claims: Update your parsing logic to the new hierarchical structure:

Data

Legacy Claim

FAPI 2.0 Claim

Entity Details

entityInfo.*

{
  "entityInfo": {
    "CPEntID": "T09LL0001B",
    "CPEnt_TYPE": "UEN",
    "CPEnt_Status": "Registered",
    "CPNonUEN_Country": "",
    "CPNonUEN_RegNo": "",
    "CPNonUEN_Name": ""
  }
}

sub, sub_attributes.*

{
  "sub": "T09LL0001B",
  "sub_type": "entity",
  "sub_attributes": {
    "entity_type": "UEN",
    "entity_reg_number": "T09LL0001B",
    "entity_coi": "SG",
    "entity_name": "My Example Company",
    "entity_uen_status": "Registered"
  }
}

User Details

sub

{
  "sub": "s=S1234567P,uuid=0f14a2fc-09c2-4780-95f0-8c28347f2780,u=CP192,c=SG"
}

userInfo.*

{
  "userInfo":{
    "CPAccType": "User",
    "CPUID_FullName": "John Grisham",
    "ISSPHOLDER": "YES"
  },
  "email": "[email protected]",
  "email_verified": true
}

act.*

{
  "act": {
    "sub": "0f14a2fc-09c2-4780-95f0-8c28347f2780",
    "sub_type": "user",
    "sub_attributes": {
      "account_type": "standard", 
      "identity_number": "S1234567P",
      "identity_coi": "SG",
      "name": "John Grisham",
      "email": "[email protected]",
      "email_verified": true
    }
  }
}

Refer to the ID Token section for more details.

Step 6: Userinfo Endpoint

If your application fetches additional user data:

Endpoint: Use the Userinfo Endpoint (/userinfo) retrieved in Step 2 (userinfo_endpoint).
Prepare the Request:
1. Mandatory DPoP: Include the DPoP HTTP header in the GET request. This must be signed with the same key used for the Token Exchange.
Response Format: Update your JSON parser to handle snake_case keys (e.g., auth_info instead of AuthInfo).

Refer to Userinfo Endpoint for more details.

Step 7: Error Handling

Ensure your application handles standard OAuth 2.0 error parameters (error, error_description, state):

Handle Redirect URI: Error query parameters on the callback URL (e.g., https://client.com/cb?error=access_denied&error_description=...)
Handle API Response: JSON bodies for /request, /token , or userinfo failures.

Refer to the respective Endpoints for more details.

PreviousCorppass Authorization API (FAPI 2.0)NextKey concepts

Last updated 0 minutes ago