@opengovsg/mockpass

v4.9.2

Published

4 days ago

A mock SingPass/CorpPass server for dev purposes

0High
0Medium
0Low

mock test singpass corppass

MockPass

A mock Singpass/Corppass/Myinfo v3/sgID v2/Sign v3 server for dev purposes

Quick Start (hosted remotely on Gitpod)

Click the ready-to-code badge above
Wait for MockPass to start
Make port 5156 public
Open browser to note the URL hosting MockPass
Configure your application per local machine quick start, changing the localhost:5156 to the Gitpod hostname

Quick Start (hosted locally)

Singpass v3 (FAPI flow)

For more information regarding the FAPI flow, refer to: https://docs.developer.singpass.gov.sg/docs/technical-specifications/integration-guide/1.-authorization-request

Configure your endpoint to point to the following endpoints:

http://localhost:5156/singpass/v3/fapi/.well-known/openid-configuration
http://localhost:5156/singpass/v3/fapi/.well-known/keys
http://localhost:5156/singpass/v3/fapi/par
http://localhost:5156/singpass/v3/fapi/auth
http://localhost:5156/singpass/v3/fapi/token
http://localhost:5156/singpass/v3/fapi/userinfo

In the /fapi/utils.js file, you can configure your client JWKS endpoint in the fapiClientConfiguration. By default, it is set to null and Mockpass will read the default keys that are stored in the fapi-rp-private.json and fapi-rp-public.json files. If configured, Mockpass will attempt to fetch the JWKS from the specified endpoint. Your JWKS endpoint will need to be publicly accessible, and it needs to contain a valid JWKS with a sig key and an enc key.

Limitations:

client_id and redirect_uri can be set to anything.
Mockpass will not check if ephemeral keys, state, and nonce are reused.
scope accepts openid, user.identity, and any basic MyInfo attribute (uinfin, name, dob, regadd, ...)
Only urn:singpass:authentication:loa:1 is supported for the acr_values parameter.

Userinfo (MyInfo apps only)

GET /singpass/v3/fapi/userinfo returns the person data for the scopes requested at /par, as a signed-then-encrypted JWT using the same keys as the id_token. Refer to: https://docs.developer.singpass.gov.sg/docs/technical-specifications/integration-guide/5.-requesting-for-userinfo

The request takes no query parameters and requires two headers:

| Header | Value | | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Authorization | DPoP <access_token> — the access token from /token, valid for 30 minutes and reusable within that window. | | DPoP | A proof JWT with htm: GET, htu set to the userinfo endpoint, and an ath claim holding the base64url SHA-256 of the access token. It must be signed with the same ephemeral key used at /token. |

The decrypted payload looks like:

{
  "person_info": {
    "uinfin": {
      "lastupdated": "2020-04-16",
      "source": "1",
      "classification": "C",
      "value": "S9812379B"
    },
    "name": {
      "lastupdated": "2020-04-16",
      "source": "1",
      "classification": "C",
      "value": "LIM YONG XIANG"
    }
  },
  "iss": "http://localhost:5156/singpass/v3/fapi",
  "sub": "952b0342-0649-a6fe-245b-87cfcc3d38da",
  "aud": "mock-fapi-client-id",
  "iat": 1746678089
}

Notes:

Only login profiles marked [MyInfo] on the login page carry real person data. For any other profile — including one entered through the custom profile form — uinfin is filled in from the NRIC you supplied and every other attribute comes back as { "lastupdated": "", "source": "", "classification": "", "unavailable": true }.
person_info is always present, and is {} when only openid was requested. Apps that do not use MyInfo can ignore this endpoint entirely.
Errors follow the OAuth shape: invalid_token and invalid_dpop_proof at 401 (with a WWW-Authenticate header), invalid_request at 400.

Helper functions

There is a helper endpoint that can generate the ephemeral keys and tokens for you. This is useful if you want to experience the FAPI flow without a server setup.

POST: http://localhost:5156/singpass/v3/fapi/tests/generate-tokens
Request Body

| Body | Description | Example | | ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | ephemeralPrivateKey | Optional. This is the generated ephemeral private key that will be used for the auth session. If provided, it will be used to sign the DPoP tokens. Otherwise, a new key will be generated for you in the response body. Note: If you are calling the /token endpoint, you will need to pass in the generated private key so that the same key is used for signing the DPoP token. | -----BEGIN PRIVATE KEY-----\nMIGHAgE...3HMe8M82x\n-----END PRIVATE KEY----- | | endpoint | Mandatory. This is to populate the htu parameter in the DPoP token. Depending on which endpoint you are calling in the FAPI flow, you should select the correct endpoint. | Possible values are: http://localhost:5156/singpass/v3/fapi/par, http://localhost:5156/singpass/v3/fapi/token, http://localhost:5156/singpass/v3/fapi/userinfo | | method | Optional, defaults to POST. Populates the htm parameter in the DPoP token. Set this to GET when calling the userinfo endpoint. | GET | | access_token | Optional. When provided, an ath claim holding the base64url SHA-256 of this token is added to the DPoP proof. Required when calling the userinfo endpoint. | The access_token returned by /token |

Response Body

| Body | Description | Type | | -------------------- | ------------------------------------------------------------------------------------------------------------------- | ---------- | | dpopToken | The dpop token that is used for the API call. | jwt | | clientAssertionToken | The client assertion token that is used for the API call. | jwt | | ephemeralPrivateKey | The ephemeral private key that is used to sign the dpop token. This key should be used for the entire auth session. | PEM format |

Singpass v2 (NDI OIDC)

Configure your application to point to the following endpoints:

http://localhost:5156/singpass/v2/.well-known/openid-configuration
http://localhost:5156/singpass/v2/.well-known/keys
http://localhost:5156/singpass/v2/auth
http://localhost:5156/singpass/v2/token

Configure your application (or MockPass) with keys:

EITHER configure MockPass with your application's JWKS endpoint URL using the env var SP_RP_JWKS_ENDPOINT.
OR configure your application to use the private keys from static/certs/oidc-v2-rp-secret.json.

MockPass accepts any value for client_id and redirect_uri.

| Configuration item | Explanation | | ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Client signing and encryption keys | Overview: When client makes any request, what signing key is used to verify the client's signature on the client assertion, and what encryption key is used to encrypt the data payload. Default: static keyset static/certs/oidc-v2-rp-public.json is used. How to configure: Set the env var SP_RP_JWKS_ENDPOINT to a JWKS URL that MockPass can connect to. This can be a HTTP or HTTPS URL. | | Login page | Overview: When client makes an authorize request, whether MockPass sends the client to a login page, instead of completing the login silently. Default: Disabled for all requests. How to configure: Enable for all requests by default by setting the env var SHOW_LOGIN_PAGE to true. Regardless of the default, you can override on a per-request basis by sending the HTTP request header X-Show-Login-Page with the value true. Detailed effect: When login page is disabled, MockPass will immediately complete login and redirect to the redirect_uri. The profile used will be (in order of decreasing precedence) the profile specified in HTTP request headers (X-Custom-NRIC and X-Custom-UUID must both be specified), the profile with the NRIC specified in the env var MOCKPASS_NRIC, or the first profile in MockPass' static data. When login page is enabled, MockPass returns a HTML page with a form that is used to complete the login. The client may select an existing profile, or provide a custom NRIC and UUID on the form. | | ID token exchange | Overview: Singpass uses the client's profile to decide the format of the id token to send across. Default: direct How to configure: To set this, set the env var (SINGPASS_CLIENT_PROFILE) to the desired value | | Test users/profiles | Overview: The list of NRIC/UUID (and, for foreign IDs, sfa) profiles MockPass can log in as. Default: static data static/singpass/users.json is used. How to configure: Set the env var SINGPASS_USERS_PATH to the path to a JSON file with the same shape (an array of { nric, uuid }, optionally sfa: { fid, coi, RP } for NRICs starting with Y). An absolute path is recommended. |

Corppass v2 (Corppass OIDC)

Configure your application to point to the following endpoints:

http://localhost:5156/corppass/v2/.well-known/openid-configuration
http://localhost:5156/corppass/v2/.well-known/keys
http://localhost:5156/corppass/v2/auth
http://localhost:5156/corppass/v2/token

Configure your application (or MockPass) with keys:

EITHER configure MockPass with your application's JWKS endpoint URL using the env var CP_RP_JWKS_ENDPOINT. HTTP/HTTPS endpoints are supported.
OR configure your application to use the private keys from static/certs/oidc-v2-rp-secret.json.

MockPass accepts any value for client_id and redirect_uri.

| Configuration item | Explanation | | ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Client signing and encryption keys | Overview: When client makes any request, what signing key is used to verify the client's signature on the client assertion, and what encryption key is used to encrypt the data payload. Default: static keyset static/certs/oidc-v2-rp-public.json is used. How to configure: Set the env var CP_RP_JWKS_ENDPOINT to a JWKS URL that MockPass can connect to. This can be a HTTP or HTTPS URL. | | Login page | Overview: When client makes an authorize request, whether MockPass sends the client to a login page, instead of completing the login silently. Default: Disabled for all requests. How to configure: Enable for all requests by default by setting the env var SHOW_LOGIN_PAGE to true. Regardless of the default, you can override on a per-request basis by sending the HTTP request header X-Show-Login-Page with the value true. Detailed effect: When login page is disabled, MockPass will immediately complete login and redirect to the redirect_uri. The profile used will be (in order of decreasing precedence) the profile specified in HTTP request headers (X-Custom-NRIC, X-Custom-UUID, X-Custom-UEN must all be specified), the profile with the NRIC specified in the env var MOCKPASS_NRIC, or the first profile in MockPass' static data. When login page is enabled, MockPass returns a HTML page with a form that is used to complete the login. The client may select an existing profile, or provide a custom NRIC, UUID and UEN on the form. | | Test users/profiles | Overview: The list of NRIC/UUID/UEN profiles MockPass can log in as. Default: static data static/corppass/users.json is used. How to configure: Set the env var CORPPASS_USERS_PATH to the path to a JSON file with the same shape (an array of { nric, uuid, name, isSingPassHolder, uen }). An absolute path is recommended. |

Myinfo v3

Configure your application to point to the following endpoints:

http://localhost:5156/myinfo/v3/authorise
http://localhost:5156/myinfo/v3/token
http://localhost:5156/myinfo/v3/person-basic (exclusive to government systems)
http://localhost:5156/myinfo/v3/person

Configure your application (or MockPass) with certificates/keys:

Provide your application with the certificate static/certs/spcp.crt as the Myinfo public certificate.
EITHER configure MockPass with your application's X.509 certificate by setting the env vars SERVICE_PROVIDER_PUB_KEY and SERVICE_PROVIDER_CERT_PATH to the path to the certificate in PEM format. Self-signed or untrusted certificates are supported.
OR configure your application to use the certificate and private key from static/certs/(server.crt|key.pem).

MockPass accepts any value for client_id, redirect_uri and sp_esvcId. The client_secret value will be checked if configured, see below.

Only the profiles (NRICs) that have entries in Mockpass' personas dataset will succeed, using other NRICs will result in an error. See the list of personas in static/myinfo/v3.json.

| Configuration item | Explanation | | ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Client certificate | Overview: When client makes any request, what certificate is used to verify the request signature, and what certificate is used to encrypt the data payload. Default: static certificate/key static/certs/(server.crt\|key.pub) are used. How to configure: Set the env var SERVICE_PROVIDER_PUB_KEY to the path to a public key PEM file, and SERVICE_PROVIDER_CERT_PATH to the path to a certificate PEM file. (A certificate PEM file can also be provided to SERVICE_PROVIDER_PUB_KEY, despite the env var name.) | | Client secret | Overview: When client makes a Token request, whether MockPass verifies the request signature. Default: Disabled. How to configure: Enable for all requests by setting the env var SERVICE_PROVIDER_MYINFO_SECRET to some non-blank string. Provide this value to your application as well. | | Payload encryption | Overview: When client makes a Person or Person-Basic request, whether MockPass encrypts the data payload. When client makes a Person request, whether MockPass verifies the request signature. Default: Disabled. How to configure: Enable for all requests by setting the env var ENCRYPT_MYINFO to true. | | Personas/test users | Overview: The dataset of NRIC-keyed personas (Myinfo attribute values, and the UUID/profile used for login) that MockPass serves. Default: static data static/myinfo/v3.json is used. How to configure: Set the env var MYINFO_V3_USERS_PATH to the path to a JSON file with the same shape ({ attributes, personas }, where personas is keyed by NRIC). An absolute path is recommended. |

To emulate the equivalent of the Test environment on Myinfo v3, you must both set a client secret and enable payload encryption on MockPass.

sgID v2

Configure your application to point to the following endpoints:

http://localhost:5156/v2/.well-known/openid-configuration
http://localhost:5156/v2/.well-known/jwks.json
http://localhost:5156/v2/oauth/authorize
http://localhost:5156/v2/oauth/token
http://localhost:5156/v2/oauth/userinfo

Configure your application (or MockPass) with certificates/keys:

Provide your application with the certificate static/certs/spcp.crt as the sgID public key, or use the signing key published at the JWKS endpoint.
EITHER configure MockPass with your application's X.509 certificate using the env var SERVICE_PROVIDER_PUB_KEY, as the path to the certificate in PEM format. Self-signed or untrusted certificates are supported.
OR configure your application to use the certificate and private key from static/certs/(server.crt|key.pem).

MockPass accepts any value for client_id, client_secret and redirect_uri.

Only the profiles (NRICs) that have entries in Mockpass' personas dataset will succeed, using other NRICs will result in an error. See the list of personas in static/myinfo/v3.json, or the env var MYINFO_V3_USERS_PATH to override it (see the Myinfo v3 section above).

If the Public Officer Employment Details data item is requested, the pocdex.public_officer_details scope data is sourced from the publicofficerdetails data key (where present) on personas. Most personas do not have this data key configured, and will result in a "NA" response instead of an stringified array. As these personas are not identified in the login page dropdown, please check the personas dataset linked above to identify them. The pocdex.number_of_employments scope is not supported.

| Configuration item | Explanation | | ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Client certificate | Overview: When client makes any request, what certificate is used to verify the request signature, and what certificate is used to encrypt the data payload. Default: static key static/certs/key.pub is used. How to configure: Set the env var SERVICE_PROVIDER_PUB_KEY to the path to a public key PEM file. (A certificate PEM file can also be provided, despite the env var name.) | | Login page | Overview: When client makes an authorize request, whether MockPass sends the client to a login page, instead of completing the login silently. Default: Disabled for all requests. How to configure: Enable for all requests by default by setting the env var SHOW_LOGIN_PAGE to true. Regardless of the default, you can override on a per-request basis by sending the HTTP request header X-Show-Login-Page with the value true. Detailed effect: When login page is disabled, MockPass will immediately complete login and redirect to the redirect_uri. The profile used will be (in order of decreasing precedence) the profile with the NRIC specified in the env var MOCKPASS_NRIC, or the first profile in MockPass' static data. When login page is enabled, MockPass returns a HTML page with a form that is used to complete the login. The client may select an existing profile, or provide a custom NRIC and UUID on the form. |

Singpass/Corppass v1 (legacy)

The v1 APIs should no longer be in use, see the v2 APIs above!

Configure your application to point to the following endpoints:

Singpass (v1 - Singpass OIDC):

http://localhost:5156/singpass/authorize - OIDC login redirect with optional page
http://localhost:5156/singpass/token - receives OIDC authorization code and returns id_token

Corppass (v1 - Corppass OIDC):

http://localhost:5156/corppass/authorize - OIDC login redirect with optional page
http://localhost:5156/corppass/token - receives OIDC authorization code and returns id_token

Configure your application with keys and/or certificates:

Provide your application with the certificate static/certs/spcp.crt as the Singpass/Corppass public certificate. Provide the path to your application's X.509 certificate in PEM format as env var SERVICE_PROVIDER_CERT_PATH when running MockPass. Self-signed or untrusted certificates are supported. Alternatively, provide your application with the certificate and private key from static/certs/(server.crt|key.pem).

Sign v3

Check out Sign V3 documentation here.

Sign v3 URLs

http://localhost:5156/sign-v3/sign-requests - Create sign request
http://localhost:5156/sign-v3/sign-requests/:request_id/signed-doc - Get signed document
http://localhost:5156/sign-v3/jwks - JWKS URL
http://localhost:5156/sign-v3/sign - The stubbed signing portal path

Configure MockPass with your application client details:

Client ID: SIGNV3_CLIENT_ID, default mockpass-sign-v3-client
JWKS URL: SIGNV3_CLIENT_JWKS_URL, default http://localhost:4000/jwks
Redirect URL: SIGNV3_CLIENT_REDIRECT_URL, default http://localhost:4000/redirect
Webhook URL: SIGNV3_CLIENT_WEBHOOK_URL, default http://localhost:4000/webhook
Server host URL: MOCKPASS_SERVER_HOST: default: http://localhost:5156

Run MockPass

Common configuration:

Run MockPass:

$ npm install @opengovsg/mockpass

# Configure the listening port if desired, defaults to 5156
$ export MOCKPASS_PORT=5156

# Configure any other options if required
$ export SHOW_LOGIN_PAGE=false
$ export MOCKPASS_NRIC=S8979373D
$ export SERVICE_PROVIDER_MYINFO_SECRET=<your secret here>
$ export ENCRYPT_MYINFO=false

$ npx mockpass
MockPass listening on 5156

# Alternatively, just run directly with npx
MOCKPASS_PORT=5156 SHOW_LOGIN_PAGE=false MOCKPASS_NRIC=S8979373D npx @opengovsg/mockpass@latest

Contributing

We welcome contributions to code open-sourced by the Government Technology Agency of Singapore. All contributors will be asked to sign a Contributor License Agreement (CLA) in order to ensure that everybody is free to use their contributions.

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

MockPass

Quick Start (hosted remotely on Gitpod)

Quick Start (hosted locally)

Singpass v3 (FAPI flow)

Userinfo (MyInfo apps only)

Helper functions

Request Body

Response Body

Singpass v2 (NDI OIDC)

Corppass v2 (Corppass OIDC)

Myinfo v3

sgID v2

Singpass/Corppass v1 (legacy)

Sign v3

Run MockPass

Contributing