From 37943760fd5118934eb40ab6928a5110b6aa5440 Mon Sep 17 00:00:00 2001 From: Chiang Fong Lee Date: Wed, 7 Feb 2024 20:18:33 +0800 Subject: [PATCH] docs: update README (#616) --- README.md | 216 +++++++++++++++++++++++++++++++++++++----------------- 1 file changed, 147 insertions(+), 69 deletions(-) diff --git a/README.md b/README.md index d7c4480b..fcbeef39 100644 --- a/README.md +++ b/README.md @@ -1,107 +1,185 @@ # MockPass -[![Gitpod Ready-to-Code](https://img.shields.io/badge/Gitpod-ready--to--code-blue?logo=gitpod)](https://gitpod.io/#https://github.com/opengovsg/mockpass) +A mock Singpass/Corppass/Myinfo v3/sgID v2 server for dev purposes -A mock SingPass/CorpPass/MyInfo server for dev purposes +## Quick Start (hosted remotely on Gitpod) -## Quick Start (hosted by Gitpod) +[![Gitpod Ready-to-Code](https://img.shields.io/badge/Gitpod-ready--to--code-blue?logo=gitpod)](https://gitpod.io/#https://github.com/opengovsg/mockpass) - Click the ready-to-code badge above - Wait for MockPass to start - Make port 5156 public -- Open Browser to note the URL hosting MockPass +- Open browser to note the URL hosting MockPass - Configure your application per local machine quick start, changing - the localhost:5156 to the Gitpod hostname + the `localhost:5156` to the Gitpod hostname + +## Quick Start (hosted locally) + +### 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/authorize +- 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. | + +### 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/authorize +- 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. | + +### 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)`. -## Quick Start (on local machine) +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' static dataset will +succeed, using other NRICs will result in an error. See the list of personas in +[static/myinfo/v3.json](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`. | + +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: -SingPass (v1 - Singpass OIDC): +- 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' static dataset will +succeed, using other NRICs will result in an error. See the list of personas in +[static/myinfo/v3.json](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 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 -SingPass (v2 - NDI OIDC): - - http://localhost:5156/singpass/v2/authorize - OIDC login redirect with optional page - - http://localhost:5156/singpass/v2/token - receives OIDC authorization code and returns id_token - - http://localhost:5156/singpass/v2/.well-known/openid-configuration - OpenID discovery endpoint - - http://localhost:5156/singpass/v2/.well-known/keys - JWKS endpoint which exposes the auth provider's signing keys - -CorpPass (v1 - Corppass OIDC): +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 -CorpPass (v2 - Corppass OIDC): - - http://localhost:5156/corppass/v2/authorize - OIDC login redirect with optional page - - http://localhost:5156/corppass/v2/token - receives OIDC authorization code and returns id_token - - http://localhost:5156/corppass/v2/.well-known/openid-configuration - OpenID discovery endpoint - - http://localhost:5156/corppass/v2/.well-known/keys - JWKS endpoint which exposes the auth provider's signing keys +Configure your application with keys and/or certificates: -MyInfo: - - http://localhost:5156/myinfo/v3/person-basic (exclusive to government systems) - - http://localhost:5156/myinfo/v3/authorise - - http://localhost:5156/myinfo/v3/token - - http://localhost:5156/myinfo/v3/person +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)`. -sgID: - - http://localhost:5156/v2/oauth/authorize - - http://localhost:5156/v2/oauth/token - - http://localhost:5156/v2/oauth/userinfo - - http://localhost:5156/v2/.well-known/openid-configuration - OpenID discovery endpoint - - http://localhost:5156/v2/.well-known/jwks.json - JWKS endpoint which exposes the auth provider's signing keys +### Run MockPass -Provide your application with the `spcp*` certs found in `static/certs` -and with application certs at `static/certs/{key.pem|server.crt}` +Common configuration: -Alternatively, provide the paths to your app cert as env vars -`SERVICE_PROVIDER_CERT_PATH` and `SERVICE_PROVIDER_PUB_KEY` +| Configuration item | Explanation | +|---|---| +| Port number | **Overview:** What port number MockPass will listen for HTTP requests on.
**Default:** 5156.
**How to configure:** Set the env var `MOCKPASS_PORT` or `PORT` to some port number. | -If you are integrating with Singpass NDI OIDC and/or Corppass v2 OIDC, you should -provide your well-known key endpoints as env vars `SP_RP_JWKS_ENDPOINT` and/or -`CP_RP_JWKS_ENDPOINT` respectively. Alternatively, provide your application with -the `oidc-v2-rp-*.json` JWKS. +Run MockPass: ``` $ npm install @opengovsg/mockpass -# All values shown here are defaults +# Configure the listening port if desired, defaults to 5156 $ export MOCKPASS_PORT=5156 -$ export SHOW_LOGIN_PAGE=true # Optional, defaults to `false`; can be overridden per request using `X-Show-Login-Page` HTTP header - -# Configure which profile to return when login page is disabled -# Can be overridden per request using `X-Custom-NRIC`/`X-Custom-UUID`/`X-Custom-UEN` HTTP headers -$ export MOCKPASS_NRIC=S8979373D # Optional, defaults to first profile - -# Disable signing/encryption (Optional, by default `true`) -$ export SIGN_ASSERTION=false -$ export ENCRYPT_ASSERTION=false -$ export SIGN_RESPONSE=false -$ export RESOLVE_ARTIFACT_REQUEST_SIGNED=false - -# Encrypt payloads returned by /myinfo/v3/{person, person-basic}, -# equivalent to MyInfo Auth Level L2 (testing and production) -$ export ENCRYPT_MYINFO=false - -# If specified, will verify token provided in Authorization header -# for requests to /myinfo/*/token +# Configure any other options if required +$ export SHOW_LOGIN_PAGE=false +$ export MOCKPASS_NRIC=S8979373D $ export SERVICE_PROVIDER_MYINFO_SECRET= +$ export ENCRYPT_MYINFO=false $ npx mockpass MockPass listening on 5156 -``` -## Background - -There currently is nothing widely available to test an application's integration -with SingPass/CorpPass using a dev machine alone. This is awkward for developers -who then need to connect to the staging servers hosted by SingPass/CorpPass, -which may not always be available (eg, down for maintenance, or no Internet). - -MockPass tries to solves this by providing an extremely lightweight implementation -of an OIDC Provider that returns mock SingPass and CorpPass assertions. -It optionally provides a mock login page that (badly) mimics the SingPass/CorpPass -login experience. +# Alternatively, just run directly with npx +MOCKPASS_PORT=5156 SHOW_LOGIN_PAGE=false MOCKPASS_NRIC=S8979373D npx @opengovsg/mockpass@latest +``` ## Contributing