@opengovsg/mockpass 4.0.11 → 4.0.12

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (5) hide show
  1. package/.husky/pre-push +1 -1
  2. package/README.md +147 -69
  3. package/app.js +59 -0
  4. package/index.js +1 -56
  5. package/package.json +3 -3
package/.husky/pre-push CHANGED
@@ -1,4 +1,4 @@
1
1
  #!/bin/sh
2
2
  . "$(dirname "$0")/_/husky.sh"
3
3
 
4
- npx commitlint --from origin/master --to HEAD --verbose
4
+ npx commitlint --from origin/main --to HEAD --verbose
package/README.md CHANGED
@@ -1,107 +1,185 @@
1
1
  # MockPass
2
2
 
3
- [![Gitpod Ready-to-Code](https://img.shields.io/badge/Gitpod-ready--to--code-blue?logo=gitpod)](https://gitpod.io/#https://github.com/opengovsg/mockpass)
3
+ A mock Singpass/Corppass/Myinfo v3/sgID v2 server for dev purposes
4
4
 
5
- A mock SingPass/CorpPass/MyInfo server for dev purposes
5
+ ## Quick Start (hosted remotely on Gitpod)
6
6
 
7
- ## Quick Start (hosted by Gitpod)
7
+ [![Gitpod Ready-to-Code](https://img.shields.io/badge/Gitpod-ready--to--code-blue?logo=gitpod)](https://gitpod.io/#https://github.com/opengovsg/mockpass)
8
8
 
9
9
  - Click the ready-to-code badge above
10
10
  - Wait for MockPass to start
11
11
  - Make port 5156 public
12
- - Open Browser to note the URL hosting MockPass
12
+ - Open browser to note the URL hosting MockPass
13
13
  - Configure your application per local machine quick start, changing
14
- the localhost:5156 to the Gitpod hostname
14
+ the `localhost:5156` to the Gitpod hostname
15
+
16
+ ## Quick Start (hosted locally)
17
+
18
+ ### Singpass v2 (NDI OIDC)
19
+
20
+ Configure your application to point to the following endpoints:
21
+
22
+ - http://localhost:5156/singpass/v2/.well-known/openid-configuration
23
+ - http://localhost:5156/singpass/v2/.well-known/keys
24
+ - http://localhost:5156/singpass/v2/authorize
25
+ - http://localhost:5156/singpass/v2/token
26
+
27
+ Configure your application (or MockPass) with keys:
28
+
29
+ - EITHER configure MockPass with your application's JWKS endpoint URL using the env
30
+ var `SP_RP_JWKS_ENDPOINT`.
31
+ - OR configure your application to use the private keys from
32
+ `static/certs/oidc-v2-rp-secret.json`.
33
+
34
+ MockPass accepts any value for `client_id` and `redirect_uri`.
35
+
36
+ | Configuration item | Explanation |
37
+ |---|---|
38
+ | 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. <br> **Default:** static keyset `static/certs/oidc-v2-rp-public.json` is used. <br> **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. |
39
+ | Login page | **Overview:** When client makes an authorize request, whether MockPass sends the client to a login page, instead of completing the login silently. <br> **Default:** Disabled for all requests. <br> **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`. <br> **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. <br> 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. |
40
+
41
+ ### Corppass v2 (Corppass OIDC)
42
+
43
+ Configure your application to point to the following endpoints:
44
+
45
+ - http://localhost:5156/corppass/v2/.well-known/openid-configuration
46
+ - http://localhost:5156/corppass/v2/.well-known/keys
47
+ - http://localhost:5156/corppass/v2/authorize
48
+ - http://localhost:5156/corppass/v2/token
49
+
50
+ Configure your application (or MockPass) with keys:
51
+
52
+ - EITHER configure MockPass with your application's JWKS endpoint URL using the env
53
+ var `CP_RP_JWKS_ENDPOINT`. HTTP/HTTPS endpoints are supported.
54
+ - OR configure your application to use the private keys from
55
+ `static/certs/oidc-v2-rp-secret.json`.
56
+
57
+ MockPass accepts any value for `client_id` and `redirect_uri`.
58
+
59
+ | Configuration item | Explanation |
60
+ |---|---|
61
+ | 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. <br> **Default:** static keyset `static/certs/oidc-v2-rp-public.json` is used. <br> **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. |
62
+ | Login page | **Overview:** When client makes an authorize request, whether MockPass sends the client to a login page, instead of completing the login silently. <br> **Default:** Disabled for all requests. <br> **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`. <br> **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. <br> 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. |
63
+
64
+ ### Myinfo v3
65
+
66
+ Configure your application to point to the following endpoints:
67
+
68
+ - http://localhost:5156/myinfo/v3/authorise
69
+ - http://localhost:5156/myinfo/v3/token
70
+ - http://localhost:5156/myinfo/v3/person-basic (exclusive to government systems)
71
+ - http://localhost:5156/myinfo/v3/person
72
+
73
+ Configure your application (or MockPass) with certificates/keys:
74
+
75
+ - Provide your application with
76
+ the certificate `static/certs/spcp.crt` as the Myinfo public certificate.
77
+ - EITHER configure MockPass with your application's X.509 certificate by setting
78
+ the env vars `SERVICE_PROVIDER_PUB_KEY` and `SERVICE_PROVIDER_CERT_PATH` to
79
+ the path to the certificate in PEM format. Self-signed or untrusted
80
+ certificates are supported.
81
+ - OR configure your application to use the certificate and private key
82
+ from `static/certs/(server.crt|key.pem)`.
15
83
 
16
- ## Quick Start (on local machine)
84
+ MockPass accepts any value for `client_id`, `redirect_uri` and `sp_esvcId`.
85
+ The `client_secret` value will be checked if configured, see below.
86
+
87
+ Only the profiles (NRICs) that have entries in Mockpass' static dataset will
88
+ succeed, using other NRICs will result in an error. See the list of personas in
89
+ [static/myinfo/v3.json](static/myinfo/v3.json).
90
+
91
+ | Configuration item | Explanation |
92
+ |---|---|
93
+ | 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. <br> **Default:** static certificate/key `static/certs/(server.crt|key.pub)` are used. <br> **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.) |
94
+ | Client secret | **Overview:** When client makes a Token request, whether MockPass verifies the request signature. <br> **Default:** Disabled. <br> **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. |
95
+ | 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. <br> **Default:** Disabled. <br> **How to configure:** Enable for all requests by setting the env var `ENCRYPT_MYINFO` to `true`. |
96
+
97
+ To emulate the equivalent of the Test environment on Myinfo v3, you must both
98
+ set a client secret and enable payload encryption on MockPass.
99
+
100
+ ### sgID v2
17
101
 
18
102
  Configure your application to point to the following endpoints:
19
103
 
20
- SingPass (v1 - Singpass OIDC):
104
+ - http://localhost:5156/v2/.well-known/openid-configuration
105
+ - http://localhost:5156/v2/.well-known/jwks.json
106
+ - http://localhost:5156/v2/oauth/authorize
107
+ - http://localhost:5156/v2/oauth/token
108
+ - http://localhost:5156/v2/oauth/userinfo
109
+
110
+ Configure your application (or MockPass) with certificates/keys:
111
+
112
+ - Provide your application with the certificate `static/certs/spcp.crt` as the
113
+ sgID public key, or use the signing key published at the JWKS endpoint.
114
+ - EITHER configure MockPass with your application's X.509 certificate using the
115
+ env var `SERVICE_PROVIDER_PUB_KEY`, as the path to the certificate in PEM
116
+ format. Self-signed or untrusted certificates are supported.
117
+ - OR configure your application to use the certificate and private key
118
+ from `static/certs/(server.crt|key.pem)`.
119
+
120
+ MockPass accepts any value for `client_id`, `client_secret` and `redirect_uri`.
121
+
122
+ Only the profiles (NRICs) that have entries in Mockpass' static dataset will
123
+ succeed, using other NRICs will result in an error. See the list of personas in
124
+ [static/myinfo/v3.json](static/myinfo/v3.json).
125
+
126
+ | Configuration item | Explanation |
127
+ |---|---|
128
+ | 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. <br> **Default:** static key `static/certs/key.pub` is used. <br> **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.) |
129
+ | Login page | **Overview:** When client makes an authorize request, whether MockPass sends the client to a login page, instead of completing the login silently. <br> **Default:** Disabled for all requests. <br> **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`. <br> **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. <br> 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. |
130
+
131
+ ### Singpass/Corppass v1 (legacy)
132
+
133
+ **The v1 APIs should no longer be in use, see the v2 APIs above!**
134
+
135
+ Configure your application to point to the following endpoints:
136
+
137
+ Singpass (v1 - Singpass OIDC):
21
138
  - http://localhost:5156/singpass/authorize - OIDC login redirect with optional page
22
139
  - http://localhost:5156/singpass/token - receives OIDC authorization code and returns id_token
23
140
 
24
- SingPass (v2 - NDI OIDC):
25
- - http://localhost:5156/singpass/v2/authorize - OIDC login redirect with optional page
26
- - http://localhost:5156/singpass/v2/token - receives OIDC authorization code and returns id_token
27
- - http://localhost:5156/singpass/v2/.well-known/openid-configuration - OpenID discovery endpoint
28
- - http://localhost:5156/singpass/v2/.well-known/keys - JWKS endpoint which exposes the auth provider's signing keys
29
-
30
- CorpPass (v1 - Corppass OIDC):
141
+ Corppass (v1 - Corppass OIDC):
31
142
  - http://localhost:5156/corppass/authorize - OIDC login redirect with optional page
32
143
  - http://localhost:5156/corppass/token - receives OIDC authorization code and returns id_token
33
144
 
34
- CorpPass (v2 - Corppass OIDC):
35
- - http://localhost:5156/corppass/v2/authorize - OIDC login redirect with optional page
36
- - http://localhost:5156/corppass/v2/token - receives OIDC authorization code and returns id_token
37
- - http://localhost:5156/corppass/v2/.well-known/openid-configuration - OpenID discovery endpoint
38
- - http://localhost:5156/corppass/v2/.well-known/keys - JWKS endpoint which exposes the auth provider's signing keys
145
+ Configure your application with keys and/or certificates:
39
146
 
40
- MyInfo:
41
- - http://localhost:5156/myinfo/v3/person-basic (exclusive to government systems)
42
- - http://localhost:5156/myinfo/v3/authorise
43
- - http://localhost:5156/myinfo/v3/token
44
- - http://localhost:5156/myinfo/v3/person
147
+ Provide your application with the certificate `static/certs/spcp.crt` as the
148
+ Singpass/Corppass public certificate.
149
+ Provide the path to your application's X.509 certificate in PEM
150
+ format as env var `SERVICE_PROVIDER_CERT_PATH` when running MockPass.
151
+ Self-signed or untrusted certificates are supported.
152
+ Alternatively, provide your application with the certificate and private key
153
+ from `static/certs/(server.crt|key.pem)`.
45
154
 
46
- sgID:
47
- - http://localhost:5156/v2/oauth/authorize
48
- - http://localhost:5156/v2/oauth/token
49
- - http://localhost:5156/v2/oauth/userinfo
50
- - http://localhost:5156/v2/.well-known/openid-configuration - OpenID discovery endpoint
51
- - http://localhost:5156/v2/.well-known/jwks.json - JWKS endpoint which exposes the auth provider's signing keys
155
+ ### Run MockPass
52
156
 
53
- Provide your application with the `spcp*` certs found in `static/certs`
54
- and with application certs at `static/certs/{key.pem|server.crt}`
157
+ Common configuration:
55
158
 
56
- Alternatively, provide the paths to your app cert as env vars
57
- `SERVICE_PROVIDER_CERT_PATH` and `SERVICE_PROVIDER_PUB_KEY`
159
+ | Configuration item | Explanation |
160
+ |---|---|
161
+ | Port number | **Overview:** What port number MockPass will listen for HTTP requests on. <br> **Default:** 5156. <br> **How to configure:** Set the env var `MOCKPASS_PORT` or `PORT` to some port number. |
58
162
 
59
- If you are integrating with Singpass NDI OIDC and/or Corppass v2 OIDC, you should
60
- provide your well-known key endpoints as env vars `SP_RP_JWKS_ENDPOINT` and/or
61
- `CP_RP_JWKS_ENDPOINT` respectively. Alternatively, provide your application with
62
- the `oidc-v2-rp-*.json` JWKS.
163
+ Run MockPass:
63
164
 
64
165
  ```
65
166
  $ npm install @opengovsg/mockpass
66
167
 
67
- # All values shown here are defaults
168
+ # Configure the listening port if desired, defaults to 5156
68
169
  $ export MOCKPASS_PORT=5156
69
170
 
70
- $ export SHOW_LOGIN_PAGE=true # Optional, defaults to `false`; can be overridden per request using `X-Show-Login-Page` HTTP header
71
-
72
- # Configure which profile to return when login page is disabled
73
- # Can be overridden per request using `X-Custom-NRIC`/`X-Custom-UUID`/`X-Custom-UEN` HTTP headers
74
- $ export MOCKPASS_NRIC=S8979373D # Optional, defaults to first profile
75
-
76
- # Disable signing/encryption (Optional, by default `true`)
77
- $ export SIGN_ASSERTION=false
78
- $ export ENCRYPT_ASSERTION=false
79
- $ export SIGN_RESPONSE=false
80
- $ export RESOLVE_ARTIFACT_REQUEST_SIGNED=false
81
-
82
- # Encrypt payloads returned by /myinfo/v3/{person, person-basic},
83
- # equivalent to MyInfo Auth Level L2 (testing and production)
84
- $ export ENCRYPT_MYINFO=false
85
-
86
- # If specified, will verify token provided in Authorization header
87
- # for requests to /myinfo/*/token
171
+ # Configure any other options if required
172
+ $ export SHOW_LOGIN_PAGE=false
173
+ $ export MOCKPASS_NRIC=S8979373D
88
174
  $ export SERVICE_PROVIDER_MYINFO_SECRET=<your secret here>
175
+ $ export ENCRYPT_MYINFO=false
89
176
 
90
177
  $ npx mockpass
91
178
  MockPass listening on 5156
92
- ```
93
179
 
94
- ## Background
95
-
96
- There currently is nothing widely available to test an application's integration
97
- with SingPass/CorpPass using a dev machine alone. This is awkward for developers
98
- who then need to connect to the staging servers hosted by SingPass/CorpPass,
99
- which may not always be available (eg, down for maintenance, or no Internet).
100
-
101
- MockPass tries to solves this by providing an extremely lightweight implementation
102
- of an OIDC Provider that returns mock SingPass and CorpPass assertions.
103
- It optionally provides a mock login page that (badly) mimics the SingPass/CorpPass
104
- login experience.
180
+ # Alternatively, just run directly with npx
181
+ MOCKPASS_PORT=5156 SHOW_LOGIN_PAGE=false MOCKPASS_NRIC=S8979373D npx @opengovsg/mockpass@latest
182
+ ```
105
183
 
106
184
  ## Contributing
107
185
 
package/app.js ADDED
@@ -0,0 +1,59 @@
1
+ #!/usr/bin/env node
2
+ const fs = require('fs')
3
+ const express = require('express')
4
+ const morgan = require('morgan')
5
+ const path = require('path')
6
+ require('dotenv').config()
7
+
8
+ const {
9
+ configOIDC,
10
+ configOIDCv2,
11
+ configMyInfo,
12
+ configSGID,
13
+ } = require('./lib/express')
14
+
15
+ const serviceProvider = {
16
+ cert: fs.readFileSync(
17
+ path.resolve(
18
+ __dirname,
19
+ process.env.SERVICE_PROVIDER_CERT_PATH || './static/certs/server.crt',
20
+ ),
21
+ ),
22
+ pubKey: fs.readFileSync(
23
+ path.resolve(
24
+ __dirname,
25
+ process.env.SERVICE_PROVIDER_PUB_KEY || './static/certs/key.pub',
26
+ ),
27
+ ),
28
+ }
29
+
30
+ const cryptoConfig = {
31
+ signAssertion: process.env.SIGN_ASSERTION !== 'false', // default to true to be backward compatable
32
+ signResponse: process.env.SIGN_RESPONSE !== 'false',
33
+ encryptAssertion: process.env.ENCRYPT_ASSERTION !== 'false',
34
+ resolveArtifactRequestSigned:
35
+ process.env.RESOLVE_ARTIFACT_REQUEST_SIGNED !== 'false',
36
+ }
37
+
38
+ const options = {
39
+ serviceProvider,
40
+ showLoginPage: (req) =>
41
+ (req.header('X-Show-Login-Page') || process.env.SHOW_LOGIN_PAGE) === 'true',
42
+ encryptMyInfo: process.env.ENCRYPT_MYINFO === 'true',
43
+ cryptoConfig,
44
+ }
45
+
46
+ const app = express()
47
+ app.use(morgan('combined'))
48
+
49
+ configOIDC(app, options)
50
+ configOIDCv2(app, options)
51
+ configSGID(app, options)
52
+
53
+ configMyInfo.consent(app)
54
+ configMyInfo.v3(app, options)
55
+
56
+ app.enable('trust proxy')
57
+ app.use(express.static(path.join(__dirname, 'public')))
58
+
59
+ exports.app = app
package/index.js CHANGED
@@ -1,63 +1,8 @@
1
1
  #!/usr/bin/env node
2
- const fs = require('fs')
3
- const express = require('express')
4
- const morgan = require('morgan')
5
- const path = require('path')
6
- require('dotenv').config()
7
-
8
- const {
9
- configOIDC,
10
- configOIDCv2,
11
- configMyInfo,
12
- configSGID,
13
- } = require('./lib/express')
2
+ const { app } = require('./app')
14
3
 
15
4
  const PORT = process.env.MOCKPASS_PORT || process.env.PORT || 5156
16
5
 
17
- const serviceProvider = {
18
- cert: fs.readFileSync(
19
- path.resolve(
20
- __dirname,
21
- process.env.SERVICE_PROVIDER_CERT_PATH || './static/certs/server.crt',
22
- ),
23
- ),
24
- pubKey: fs.readFileSync(
25
- path.resolve(
26
- __dirname,
27
- process.env.SERVICE_PROVIDER_PUB_KEY || './static/certs/key.pub',
28
- ),
29
- ),
30
- }
31
-
32
- const cryptoConfig = {
33
- signAssertion: process.env.SIGN_ASSERTION !== 'false', // default to true to be backward compatable
34
- signResponse: process.env.SIGN_RESPONSE !== 'false',
35
- encryptAssertion: process.env.ENCRYPT_ASSERTION !== 'false',
36
- resolveArtifactRequestSigned:
37
- process.env.RESOLVE_ARTIFACT_REQUEST_SIGNED !== 'false',
38
- }
39
-
40
- const options = {
41
- serviceProvider,
42
- showLoginPage: (req) =>
43
- (req.header('X-Show-Login-Page') || process.env.SHOW_LOGIN_PAGE) === 'true',
44
- encryptMyInfo: process.env.ENCRYPT_MYINFO === 'true',
45
- cryptoConfig,
46
- }
47
-
48
- const app = express()
49
- app.use(morgan('combined'))
50
-
51
- configOIDC(app, options)
52
- configOIDCv2(app, options)
53
- configSGID(app, options)
54
-
55
- configMyInfo.consent(app)
56
- configMyInfo.v3(app, options)
57
-
58
- app.enable('trust proxy')
59
- app.use(express.static(path.join(__dirname, 'public')))
60
-
61
6
  app.listen(PORT, (err) =>
62
7
  err
63
8
  ? console.error('Unable to start MockPass', err)
package/package.json CHANGED
@@ -1,14 +1,14 @@
1
1
  {
2
2
  "name": "@opengovsg/mockpass",
3
- "version": "4.0.11",
3
+ "version": "4.0.12",
4
4
  "description": "A mock SingPass/CorpPass server for dev purposes",
5
- "main": "index.js",
5
+ "main": "app.js",
6
6
  "bin": {
7
7
  "mockpass": "index.js"
8
8
  },
9
9
  "scripts": {
10
10
  "test": "echo \"Error: no test specified\" && exit 1",
11
- "start": "nodemon",
11
+ "start": "nodemon index",
12
12
  "cz": "git-cz",
13
13
  "lint": "eslint lib",
14
14
  "lint-fix": "eslint --fix lib",