@simpleview/sv-auth-client 6.23.3 → 6.25.1
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.
- package/package.json +1 -1
- package/readme.md +40 -0
- package/src/Oauth2Express.js +22 -3
- package/src/index.js +1 -1
- package/src/oauth2.js +88 -6
- package/src/utils.js +86 -0
package/package.json
CHANGED
package/readme.md
CHANGED
|
@@ -370,6 +370,42 @@ Returns a token and refresh_token.
|
|
|
370
370
|
* `authUrl` - optional string - The URL of the auth system the website should utilise. Defaults to the live auth system. If you need to reference another system you can pass it here. Usually only used when testing in non-production environments.
|
|
371
371
|
* `refresh_token` - string - This should be a valid refresh token previously obtained from auth.
|
|
372
372
|
|
|
373
|
+
#### Embed handoff (token-exchange)
|
|
374
|
+
|
|
375
|
+
For iframe / CHIPS SSO, a parent BFF exchanges a fresh access token for a short-lived handoff JWT, delivers it to the embed (e.g. `postMessage`), and the embed BFF redeems it for user tokens. Both calls hit `POST /oauth2/token/` with `grant_type=urn:ietf:params:oauth:grant-type:token-exchange`.
|
|
376
|
+
|
|
377
|
+
Integration contract for iframe `postMessage`, origins, and cookies: [embed-iframe-sso.md](../../embed-iframe-sso.md).
|
|
378
|
+
|
|
379
|
+
* Parent should refresh its access token before hop 1 if it is near expiry.
|
|
380
|
+
* Parent `oauth_client` must list the target `audience` in `token_exchange_audiences`.
|
|
381
|
+
* Hop 1 returns a signed `embed_handoff` JWT (~60s). Mongo stores only the JWT `jti` for single-use replay protection.
|
|
382
|
+
* Hop 2 redeems that JWT once for `token` + `refresh_token`.
|
|
383
|
+
* Export: `EMBED_HANDOFF_TOKEN_TYPE` — `urn:simpleview:params:oauth:token-type:embed_handoff` (hop 2 `subject_token_type`).
|
|
384
|
+
|
|
385
|
+
#### oauth2ExchangeToken
|
|
386
|
+
|
|
387
|
+
Hop 1 — exchange a parent access JWT for an embed handoff JWT.
|
|
388
|
+
|
|
389
|
+
Returns `{ handoff_token, expires_in }`.
|
|
390
|
+
|
|
391
|
+
* args
|
|
392
|
+
* `authUrl` - optional string - The URL of the auth system. Defaults to live auth.
|
|
393
|
+
* `client_id` - string - Parent oauth client id (e.g. `crm3`).
|
|
394
|
+
* `subject_token` - string - Fresh parent access JWT.
|
|
395
|
+
* `audience` - string - Target audience (e.g. `apex`).
|
|
396
|
+
|
|
397
|
+
#### oauth2RedeemHandoffToken
|
|
398
|
+
|
|
399
|
+
Hop 2 — redeem an embed handoff JWT for user access + refresh tokens.
|
|
400
|
+
|
|
401
|
+
Returns `{ token, refresh_token }`.
|
|
402
|
+
|
|
403
|
+
* args
|
|
404
|
+
* `authUrl` - optional string - The URL of the auth system. Defaults to live auth.
|
|
405
|
+
* `client_id` - string - Same parent oauth client id used in hop 1.
|
|
406
|
+
* `subject_token` - string - The `handoff_token` from hop 1.
|
|
407
|
+
* `audience` - string - Same audience used in hop 1.
|
|
408
|
+
|
|
373
409
|
### OAuth2Express
|
|
374
410
|
|
|
375
411
|
The OAuth2Express class provides a simple interface to allow products using Express to easily add OAuth 2.0 authentication with auth. See the [sv-auth](https://github.com/simpleviewinc/sv-auth) readme for sample usage.
|
|
@@ -398,12 +434,16 @@ This method must be registered on the callback route. It takes the same paramete
|
|
|
398
434
|
|
|
399
435
|
It obtains a `token`, `refresh_token` and user from auth, stores them in the session and then redirects the user back to the original path.
|
|
400
436
|
|
|
437
|
+
`redirectUrl` is allowlisted to same-origin URLs and safe relative `/` paths. Unsafe values redirect to `/`. A missing `redirectUrl` still results in an error.
|
|
438
|
+
|
|
401
439
|
#### OAuth2Express.logout
|
|
402
440
|
|
|
403
441
|
This method must be registered on the logout route. It takes the same parameters as an Express route `(req, res)`.
|
|
404
442
|
|
|
405
443
|
It deletes the session entry and redirects the user to the auth logout route, which logs the user out from auth and then redirects to the auth login.
|
|
406
444
|
|
|
445
|
+
The same `redirectUrl` allowlist applies. Unsafe values fall back to the request origin. Relative paths are made absolute before being passed to Auth as `redirect_uri`.
|
|
446
|
+
|
|
407
447
|
#### OAuth2Express.applyMiddleware
|
|
408
448
|
|
|
409
449
|
This is a helper method which registers the `callback` and `logout` functions on the `callbackPath` and `logoutPath` respectively.
|
package/src/Oauth2Express.js
CHANGED
|
@@ -9,6 +9,10 @@ const {
|
|
|
9
9
|
oauth2GetTokens,
|
|
10
10
|
oauth2GetTokensFromRefresh
|
|
11
11
|
} = require("./oauth2");
|
|
12
|
+
const {
|
|
13
|
+
getRequestOrigin,
|
|
14
|
+
safeRedirectUrl
|
|
15
|
+
} = require("./utils");
|
|
12
16
|
|
|
13
17
|
class Oauth2Express {
|
|
14
18
|
/**
|
|
@@ -190,7 +194,7 @@ async function callback(req, res) {
|
|
|
190
194
|
}
|
|
191
195
|
session.oauth2 = newSession;
|
|
192
196
|
|
|
193
|
-
return res.redirect(302,
|
|
197
|
+
return res.redirect(302, allowedRedirect(req, redirectUrl, "/"));
|
|
194
198
|
}
|
|
195
199
|
|
|
196
200
|
/**
|
|
@@ -201,8 +205,9 @@ async function callback(req, res) {
|
|
|
201
205
|
function logout(req, res) {
|
|
202
206
|
delete req[this.sessionKey].oauth2;
|
|
203
207
|
|
|
204
|
-
const
|
|
205
|
-
const
|
|
208
|
+
const origin = getRequestOrigin(req);
|
|
209
|
+
const sanitized = allowedRedirect(req, req.query.redirectUrl, `${origin}/`);
|
|
210
|
+
const redirectUrl = sanitized.startsWith("/") ? `${origin}${sanitized}` : sanitized;
|
|
206
211
|
|
|
207
212
|
const logoutUrl = oauth2CreateLogoutUrl({
|
|
208
213
|
authUrl: this.authUrl,
|
|
@@ -213,4 +218,18 @@ function logout(req, res) {
|
|
|
213
218
|
return res.redirect(302, logoutUrl);
|
|
214
219
|
}
|
|
215
220
|
|
|
221
|
+
/**
|
|
222
|
+
* @param {import("express").Request} req
|
|
223
|
+
* @param {unknown} raw
|
|
224
|
+
* @param {string} fallback
|
|
225
|
+
* @returns {string}
|
|
226
|
+
*/
|
|
227
|
+
function allowedRedirect(req, raw, fallback) {
|
|
228
|
+
if (typeof raw !== "string") {
|
|
229
|
+
return fallback;
|
|
230
|
+
}
|
|
231
|
+
|
|
232
|
+
return safeRedirectUrl(raw, req) ?? fallback;
|
|
233
|
+
}
|
|
234
|
+
|
|
216
235
|
module.exports = Oauth2Express;
|
package/src/index.js
CHANGED
package/src/oauth2.js
CHANGED
|
@@ -5,6 +5,10 @@ const { base64urlEncode } = require("./utils");
|
|
|
5
5
|
|
|
6
6
|
const liveAuthUrl = "https://auth.simpleviewinc.com/";
|
|
7
7
|
|
|
8
|
+
const TOKEN_EXCHANGE_GRANT = "urn:ietf:params:oauth:grant-type:token-exchange";
|
|
9
|
+
const SUBJECT_TOKEN_TYPE_ACCESS_TOKEN = "urn:ietf:params:oauth:token-type:access_token";
|
|
10
|
+
const EMBED_HANDOFF_TOKEN_TYPE = "urn:simpleview:params:oauth:token-type:embed_handoff";
|
|
11
|
+
|
|
8
12
|
function oauth2CreateKeyHash(key) {
|
|
9
13
|
return base64urlEncode(createHash("sha256").update(key).digest("base64"));
|
|
10
14
|
}
|
|
@@ -75,13 +79,13 @@ function oauth2CreateRandomKey() {
|
|
|
75
79
|
}
|
|
76
80
|
|
|
77
81
|
/**
|
|
78
|
-
* Internal
|
|
82
|
+
* Internal POST to /oauth2/token/
|
|
79
83
|
* @param {object} args
|
|
80
84
|
* @param {string} args.authUrl - URL of Auth
|
|
81
85
|
* @param {object} args.params - Params to add to the request
|
|
82
|
-
* @returns {Promise<
|
|
86
|
+
* @returns {Promise<object>}
|
|
83
87
|
*/
|
|
84
|
-
async function
|
|
88
|
+
async function _oauth2PostToken({
|
|
85
89
|
authUrl = liveAuthUrl,
|
|
86
90
|
params
|
|
87
91
|
}) {
|
|
@@ -103,9 +107,25 @@ async function _oauth2GetTokens({
|
|
|
103
107
|
throw new Error(`Auth Error: ${e.message}`);
|
|
104
108
|
}
|
|
105
109
|
|
|
110
|
+
return rtn.data;
|
|
111
|
+
}
|
|
112
|
+
|
|
113
|
+
/**
|
|
114
|
+
* Internal function to retreive tokens from the server
|
|
115
|
+
* @param {object} args
|
|
116
|
+
* @param {string} args.authUrl - URL of Auth
|
|
117
|
+
* @param {object} args.params - Params to add to the request
|
|
118
|
+
* @returns {Promise<{ token: string, refresh_token: string }>}
|
|
119
|
+
*/
|
|
120
|
+
async function _oauth2GetTokens({
|
|
121
|
+
authUrl = liveAuthUrl,
|
|
122
|
+
params
|
|
123
|
+
}) {
|
|
124
|
+
const data = await _oauth2PostToken({ authUrl, params });
|
|
125
|
+
|
|
106
126
|
return {
|
|
107
|
-
token:
|
|
108
|
-
refresh_token:
|
|
127
|
+
token: data.access_token,
|
|
128
|
+
refresh_token: data.refresh_token
|
|
109
129
|
}
|
|
110
130
|
}
|
|
111
131
|
|
|
@@ -141,11 +161,73 @@ async function oauth2GetTokensFromRefresh({
|
|
|
141
161
|
});
|
|
142
162
|
}
|
|
143
163
|
|
|
164
|
+
/**
|
|
165
|
+
* Exchange a parent access token for an embed handoff JWT (token-exchange hop 1).
|
|
166
|
+
* @param {object} args
|
|
167
|
+
* @param {string} args.authUrl - URL of Auth
|
|
168
|
+
* @param {string} args.client_id - Parent oauth client_id
|
|
169
|
+
* @param {string} args.subject_token - Fresh parent access JWT
|
|
170
|
+
* @param {string} args.audience - Target audience string (e.g. apex)
|
|
171
|
+
* @returns {Promise<{ handoff_token: string, expires_in: number }>}
|
|
172
|
+
*/
|
|
173
|
+
async function oauth2ExchangeToken({
|
|
174
|
+
authUrl,
|
|
175
|
+
client_id,
|
|
176
|
+
subject_token,
|
|
177
|
+
audience
|
|
178
|
+
}) {
|
|
179
|
+
const data = await _oauth2PostToken({
|
|
180
|
+
authUrl,
|
|
181
|
+
params: {
|
|
182
|
+
grant_type: TOKEN_EXCHANGE_GRANT,
|
|
183
|
+
client_id,
|
|
184
|
+
subject_token,
|
|
185
|
+
subject_token_type: SUBJECT_TOKEN_TYPE_ACCESS_TOKEN,
|
|
186
|
+
audience
|
|
187
|
+
}
|
|
188
|
+
});
|
|
189
|
+
|
|
190
|
+
return {
|
|
191
|
+
handoff_token: data.access_token,
|
|
192
|
+
expires_in: data.expires_in
|
|
193
|
+
};
|
|
194
|
+
}
|
|
195
|
+
|
|
196
|
+
/**
|
|
197
|
+
* Redeem an embed handoff JWT for user access + refresh tokens (token-exchange hop 2).
|
|
198
|
+
* @param {object} args
|
|
199
|
+
* @param {string} args.authUrl - URL of Auth
|
|
200
|
+
* @param {string} args.client_id - Parent oauth client_id
|
|
201
|
+
* @param {string} args.subject_token - embed_handoff JWT from hop 1
|
|
202
|
+
* @param {string} args.audience - Target audience string (must match hop 1)
|
|
203
|
+
* @returns {Promise<{ token: string, refresh_token: string }>}
|
|
204
|
+
*/
|
|
205
|
+
async function oauth2RedeemHandoffToken({
|
|
206
|
+
authUrl,
|
|
207
|
+
client_id,
|
|
208
|
+
subject_token,
|
|
209
|
+
audience
|
|
210
|
+
}) {
|
|
211
|
+
return _oauth2GetTokens({
|
|
212
|
+
authUrl,
|
|
213
|
+
params: {
|
|
214
|
+
grant_type: TOKEN_EXCHANGE_GRANT,
|
|
215
|
+
client_id,
|
|
216
|
+
subject_token,
|
|
217
|
+
subject_token_type: EMBED_HANDOFF_TOKEN_TYPE,
|
|
218
|
+
audience
|
|
219
|
+
}
|
|
220
|
+
});
|
|
221
|
+
}
|
|
222
|
+
|
|
144
223
|
module.exports = {
|
|
145
224
|
oauth2CreateKeyHash,
|
|
146
225
|
oauth2CreateLoginUrl,
|
|
147
226
|
oauth2CreateLogoutUrl,
|
|
148
227
|
oauth2CreateRandomKey,
|
|
149
228
|
oauth2GetTokens,
|
|
150
|
-
oauth2GetTokensFromRefresh
|
|
229
|
+
oauth2GetTokensFromRefresh,
|
|
230
|
+
oauth2ExchangeToken,
|
|
231
|
+
oauth2RedeemHandoffToken,
|
|
232
|
+
EMBED_HANDOFF_TOKEN_TYPE
|
|
151
233
|
}
|
package/src/utils.js
CHANGED
|
@@ -29,5 +29,91 @@ const base64urlEncode = function (inputString) {
|
|
|
29
29
|
.replace(/\//g, "_");
|
|
30
30
|
}
|
|
31
31
|
|
|
32
|
+
const SAFE_RELATIVE_REDIRECT = /^\/(?!\/)[A-Za-z0-9._~!$&'()*+,;=:@/?%#-]*$/;
|
|
33
|
+
|
|
34
|
+
/**
|
|
35
|
+
* @param {import("express").Request} req
|
|
36
|
+
* @returns {string | undefined}
|
|
37
|
+
*/
|
|
38
|
+
function getRequestOrigin(req) {
|
|
39
|
+
const protocol = String(req.protocol || "").replace(/:$/, "");
|
|
40
|
+
const hostname = String(req.hostname || "").toLowerCase();
|
|
41
|
+
|
|
42
|
+
// Match Oauth2Express middleware: protocol + hostname (no Host port).
|
|
43
|
+
if ((protocol === "http" || protocol === "https") && hostname) {
|
|
44
|
+
return `${protocol}://${hostname}`;
|
|
45
|
+
}
|
|
46
|
+
|
|
47
|
+
return hostname ? `https://${hostname}` : undefined;
|
|
48
|
+
}
|
|
49
|
+
|
|
50
|
+
/**
|
|
51
|
+
* @param {string} value
|
|
52
|
+
* @param {string} [base]
|
|
53
|
+
* @returns {URL | undefined}
|
|
54
|
+
*/
|
|
55
|
+
function parseUrl(value, base) {
|
|
56
|
+
try {
|
|
57
|
+
return base ? new URL(value, base) : new URL(value);
|
|
58
|
+
} catch (err) {
|
|
59
|
+
if (err instanceof TypeError) {
|
|
60
|
+
return undefined;
|
|
61
|
+
}
|
|
62
|
+
|
|
63
|
+
throw err;
|
|
64
|
+
}
|
|
65
|
+
}
|
|
66
|
+
|
|
67
|
+
/**
|
|
68
|
+
* Allow same-origin absolute URLs and safe relative `/` paths.
|
|
69
|
+
* Returns a normalized URL, or undefined when the value is unsafe.
|
|
70
|
+
* @param {string} redirectUrl
|
|
71
|
+
* @param {import("express").Request} req
|
|
72
|
+
* @returns {string | undefined}
|
|
73
|
+
*/
|
|
74
|
+
function safeRedirectUrl(redirectUrl, req) {
|
|
75
|
+
if (typeof redirectUrl !== "string" || redirectUrl.length === 0 || redirectUrl.includes("\\")) {
|
|
76
|
+
return undefined;
|
|
77
|
+
}
|
|
78
|
+
|
|
79
|
+
const requestHost = String(req.hostname || "").toLowerCase();
|
|
80
|
+
const origin = getRequestOrigin(req);
|
|
81
|
+
/** @type {string | undefined} */
|
|
82
|
+
let result;
|
|
83
|
+
|
|
84
|
+
if (SAFE_RELATIVE_REDIRECT.test(redirectUrl)) {
|
|
85
|
+
if (/%(2f|5c)/i.test(redirectUrl) || !origin || !requestHost) {
|
|
86
|
+
return undefined;
|
|
87
|
+
}
|
|
88
|
+
|
|
89
|
+
const resolved = parseUrl(redirectUrl, origin);
|
|
90
|
+
if (!resolved || resolved.hostname.toLowerCase() !== requestHost || resolved.pathname.startsWith("//")) {
|
|
91
|
+
return undefined;
|
|
92
|
+
}
|
|
93
|
+
|
|
94
|
+
result = `${resolved.pathname}${resolved.search}${resolved.hash}`;
|
|
95
|
+
} else {
|
|
96
|
+
const parsed = parseUrl(redirectUrl);
|
|
97
|
+
if (!parsed || (parsed.protocol !== "http:" && parsed.protocol !== "https:")) {
|
|
98
|
+
return undefined;
|
|
99
|
+
}
|
|
100
|
+
|
|
101
|
+
if (parsed.username || parsed.password || parsed.pathname.startsWith("//")) {
|
|
102
|
+
return undefined;
|
|
103
|
+
}
|
|
104
|
+
|
|
105
|
+
const host = parsed.hostname.toLowerCase();
|
|
106
|
+
if (!requestHost || host !== requestHost || !origin) {
|
|
107
|
+
return undefined;
|
|
108
|
+
}
|
|
109
|
+
|
|
110
|
+
result = `${origin}${parsed.pathname}${parsed.search}${parsed.hash}`;
|
|
111
|
+
}
|
|
112
|
+
|
|
113
|
+
return result;
|
|
114
|
+
}
|
|
115
|
+
|
|
32
116
|
module.exports.canIds = canIds;
|
|
33
117
|
module.exports.base64urlEncode = base64urlEncode;
|
|
118
|
+
module.exports.getRequestOrigin = getRequestOrigin;
|
|
119
|
+
module.exports.safeRedirectUrl = safeRedirectUrl;
|