Corppass Authorization API V2

Introduction

This technical specification outlines the web-based Application Programming Interfaces (APIs) provided by Corppass for use by Relying Parties (RPs).

It defines the required endpoints and interactions to:

• Initiate user authentication using the OpenID Connect (OIDC) protocol

• Retrieve identity and authorization information securely and reliably

Corppass adopts the OpenID Foundation’s Financial-grade API (FAPI) 2.0 Security Profile, a high-assurance security standard built on top of OAuth 2.0 and OpenID Connect.

This ensures that all authentication and authorization flows are protected using:

• JWE-encrypted ID tokens

• JWT-based client authentication (client assertions)

• Sender-constrained access tokens via DPoP (Demonstration of Proof of Possession)

Flow Diagram

The diagram below illustrates the high-level OIDC flow between an RP and Corppass, highlighting the key steps in user authentication and authorization data retrieval.

Flow Breakdown

1. Discover OpenID Provider Configuration

   • Retrieve the details of the OpenID Provider by querying the OpenID Discovery endpoint. Refer to the OpenID Discovery Endpoint section.

2. Send Pushed Authorisation Request (PAR)

   • Submit the authorization request parameters (e.g., scope, redirect URI, client assertion, PKCE) to the /request endpoint. Corppass returns a request_uri referencing the validated request object. Refer to the Pushed Authorization Request (PAR) section.

3. Initiate Authorization Request

   • Redirect the user to the /mga/sps/oauth/oauth20/authorize endpoint with the request_uri to obtain an authorization code. Refer to the Authorization Endpoint section.

4. User Authentication

   • The user will be prompted to log in with Singpass and authenticate using their Singpass credentials.

5. Receive authorization code on Redirect URL

   1. The user will be redirected to the RP's redirect URL along with the authorization code.

6. Token Exchange

   • Exchange the DPoP proof, authorization code and client assertion at the Token Endpoint to obtain the ID token and access token. Refer to the Token Endpoint section.

7. ID Token Encryption

   • Corppass retrieves the RP's encryption public key from the client’s JWKS during the token issuance process.

   • Corppass then constructs the ID token JWE, along with a DPoP-bound access token.

   • Refer to the ID Token Structure section.

8. ID Token Signature Validation

   • The RP retrieves Corppass's signing public key from the JWKS endpoint to validate the signature of the ID token. Refer to the ID Token Structure section.

9. Retrieve User and Entity Information

   • Use the access token and matching DPoP proof to call the Userinfo Endpoint to retrieve the Corppass user’s authorization and selected entity details. Refer to the Userinfo Endpoint section

Step 9 is optional only applies to Relying Parties (RPs) that need to retrieve additional data from the Userinfo Endpoint, such as authorization information.

For RPs that do not need to request for authorization information, these steps can be safely skipped.