@muze-nl/metro-oidc 0.9.0 → 0.9.2

package/docs/reference.md

@@ -29,11 +29,23 @@ const api = client('https://example.solidcommunity.net/')
   }))
 ```
 
-Adds OpenID Connect authorization to a Metro client. By default it tries the request first and authorizes after a `401` or `403`. Set `force_authorization: true` to authorize immediately.
+Adds OpenID Connect authorization to a Metro client. By default it tries the request first and authorizes after a `401` or `403`. Set `force_authorization: true` to authorize immediately. `oidcmw()` checks the status of the response itself, so add middleware that turns responses into errors or data, such as `thrower()` and `getdata()`, after it: `client.with(oidcmw(options)).with(thrower())`.
 
-Important options: `issuer`, `client_info`, `client`, `openid_configuration`, `oauth2`, `store`, `scope`, `nonce`, `use_dpop`, `force_authorization`, and `authorize_callback`.
+Important options: `issuer`, `client_info`, `webid`, `login_hint`, `expected_claims`, `client`, `openid_configuration`, `oauth2`, `store`, `scope`, `nonce`, `use_dpop`, `force_authorization`, and `authorize_callback`.
 
-`use_dpop` defaults to `true`. Disable it only for providers or tests that do not support DPoP.
+`use_dpop` defaults to `true`. Disable it only for providers or tests that do not support DPoP. With `use_dpop`, only DPoP-bound access tokens are accepted: a Bearer token from the issuer is refused, as RFC 9449 section 5.10 requires when DPoP protection matters.
+
+### Which user
+
+Tokens are stored per issuer. To keep different users at the same issuer apart, tell `oidcmw()` which user it acts for:
+
+- `webid`: the user's WebID. It is sent to the issuer as `login_hint`, and the ID token's `webid` claim must match it. Older Solid issuers without a `webid` claim are matched on `sub`.
+- `login_hint`: without a WebID, a hint for the issuer about which user should log in.
+- `expected_claims`: without a WebID, claims the ID token must contain, e.g. `{ sub: '…' }`.
+
+With `webid` or `login_hint`, tokens and the ID token are stored for that user only, so logging in as another user never reuses them. An ID token for a different user than expected is refused and not stored, even when the issuer still has a login session for that other user. Pass the same `webid` or `login_hint` to `idToken()` and `idTokenClaims()`.
+
+Without a `scope` option, `oidcmw()` requests `openid webid` when a `webid` is given or the issuer lists `webid` in its `scopes_supported`: Solid-OIDC issuers only include the `webid` claim for that scope. Otherwise it requests `openid`.
 
 ## `discover(options)`
 
@@ -43,6 +55,8 @@ const config = await discover({ issuer: 'https://solidcommunity.net/' })
 
 Fetches OIDC discovery metadata. Pass a Metro client with `client` when you want custom middleware or tests.
 
+The metadata must be for the requested issuer (only a trailing slash may differ), must contain `authorization_endpoint`, `token_endpoint` and `jwks_uri`, and the issuer and all its endpoints must use `https`. Plain `http` is only accepted on the local machine (`localhost`, `127.0.0.1`, `[::1]`). These checks always run; the complete metadata schema is only checked when assertions are enabled.
+
 ## `register(options)`
 
 ```js
@@ -55,7 +69,7 @@ const info = await register({
 })
 ```
 
-Performs dynamic client registration and returns client information. `oidcmw()` calls this automatically when no `client_info.client_id` is present and the issuer supports registration.
+Performs dynamic client registration and returns client information. `oidcmw()` calls this automatically when no `client_info.client_id` is present and the issuer supports registration. It then registers a public client: it asks for `token_endpoint_auth_method: 'none'`, `grant_types: ['authorization_code', 'refresh_token']` and `response_types: ['code']`, unless `client_info` says otherwise, and it uses the authentication method the issuer registered. A public client's secret, if an issuer returns one anyway, is not stored.
 
 ## ID token helpers
 
@@ -64,7 +78,7 @@ const raw = idToken({ issuer: 'https://solidcommunity.net/' })
 const claims = idTokenClaims({ issuer: 'https://solidcommunity.net/' })
 ```
 
-Returns the stored raw ID token or validated claims. Pass the same `issuer` or `store` used by the middleware.
+Returns the stored raw ID token or validated claims. Pass the same `issuer` and `webid` or `login_hint`, or the same `store`, used by the middleware.
 
 ## `validateIdToken(idToken, options)`
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@muze-nl/metro-oidc",
-  "version": "0.9.0",
+  "version": "0.9.2",
   "description": "oidc client middleware for @muze-nl/metro",
   "type": "module",
   "source": [

package/src/oidc.discovery.mjs

@@ -30,10 +30,13 @@ export default async function oidcDiscovery(options={}) {
 
 	options = Object.assign({},defaultOptions,options)
 	options.client = options.client.with(throwermw()).with(jsonmw())
+	requireSecureURL('issuer', options.issuer)
 
-	const TestSucceeded = false
 	function MustUseHTTPS(url) {
-		return TestSucceeded // FIXME todo
+		if (isSecureURL(url)) {
+			return false
+		}
+		return error('url must use https', url)
 	}
 
 	// https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderMetadata
@@ -91,9 +94,89 @@ export default async function oidcDiscovery(options={}) {
 		configURL
 	)
 	const openid_config = response.data
+	// the full metadata schema is a diagnostic, only checked when assertions
+	// are enabled; the checks that protect the login always run
 	assert(openid_config, openid_provider_metadata)
-
-	// https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderConfigurationValidation
-	assert(openid_config.issuer, options.issuer)
+	checkProviderMetadata(openid_config, options.issuer)
 	return openid_config
+}
+
+const REQUIRED_ENDPOINTS = ['authorization_endpoint', 'token_endpoint', 'jwks_uri']
+
+/**
+ * The metadata the login depends on, checked whether or not assertions are
+ * enabled: the document must describe the issuer it was fetched for
+ * (Discovery section 4.3), so iss checks compare against the right issuer,
+ * and every endpoint that receives codes, tokens or keys must use https.
+ */
+function checkProviderMetadata(config, issuer)
+{
+	if (!config || typeof config !== 'object') {
+		throw metro.metroError('metro.oidc.discovery: openid-configuration for '+issuer+' is not a JSON object')
+	}
+	if (!sameIssuer(config.issuer, issuer)) {
+		throw metro.metroError('metro.oidc.discovery: openid-configuration is for issuer '+config.issuer+', expected '+issuer)
+	}
+	requireSecureURL('issuer', config.issuer)
+	for (const name of REQUIRED_ENDPOINTS) {
+		if (!config[name]) {
+			throw metro.metroError('metro.oidc.discovery: openid-configuration for '+issuer+' has no '+name)
+		}
+		requireSecureURL(name, config[name])
+	}
+	if (config.registration_endpoint) {
+		requireSecureURL('registration_endpoint', config.registration_endpoint)
+	}
+}
+
+/**
+ * Issuer identifiers must be identical. The only difference allowed is a
+ * trailing slash, which WebID profiles and discovery documents often
+ * disagree on.
+ */
+function sameIssuer(discovered, requested)
+{
+	if (typeof discovered != 'string') {
+		return false
+	}
+	return withoutTrailingSlash(discovered) === withoutTrailingSlash(String(requested))
+}
+
+function withoutTrailingSlash(value)
+{
+	return value.replace(/\/$/, '')
+}
+
+function requireSecureURL(name, value)
+{
+	if (!isSecureURL(value)) {
+		throw metro.metroError('metro.oidc.discovery: '+name+' must use https: '+value)
+	}
+}
+
+/**
+ * https is required; plain http is only accepted on the local machine, for
+ * development servers.
+ */
+function isSecureURL(value)
+{
+	let url
+	try {
+		url = new URL(String(value))
+	}
+	catch(e) {
+		return false
+	}
+	if (url.protocol == 'https:') {
+		return true
+	}
+	return url.protocol == 'http:' && isLoopback(url.hostname)
+}
+
+function isLoopback(hostname)
+{
+	return hostname == 'localhost'
+		|| hostname.endsWith('.localhost')
+		|| hostname == '127.0.0.1'
+		|| hostname == '[::1]'
 }

package/src/oidc.mockserver.mjs

@@ -73,7 +73,12 @@ export default function oidcmockserver(options = {}) {
 		client_secret: options.client_secret,
 		redirect_uri: options.redirect_uri,
 		scope: 'openid profile email',
-		id_token: tokenContext => idToken(tokenContext),
+		id_token: tokenContext => {
+			if (tokenContext.grant_type == 'refresh_token' && options.refreshIdToken === false) {
+				return undefined
+			}
+			return idToken(tokenContext)
+		},
 		requirePKCE: options.requirePKCE ?? false
 	})
 	const clients = new Map()
@@ -109,7 +114,7 @@ export default function oidcmockserver(options = {}) {
 			userinfo_endpoint: endpoint('/userinfo/'),
 			jwks_uri: endpoint('/jwks/'),
 			registration_endpoint: endpoint('/register/'),
-			scopes_supported: ['openid', 'profile', 'email'],
+			scopes_supported: options.scopes_supported ?? ['openid', 'profile', 'email'],
 			response_types_supported: ['code', 'id_token', 'id_token token'],
 			grant_types_supported: ['authorization_code', 'refresh_token'],
 			subject_types_supported: ['public'],

package/src/oidcmw.mjs

@@ -9,6 +9,30 @@ import jsonmw from '@muze-nl/metro-middleware/json'
 import throwermw from '@muze-nl/metro-middleware/thrower'
 import { validateIdToken } from './oidc.jwt.mjs'
 
+const pendingClientSetups = new Map()
+
+/**
+ * A browser app cannot keep a client secret, so it registers as a public
+ * client (Solid-OIDC section 11.3: secrets should not be stored in browser
+ * storage). The refresh_token grant is requested so issuers hand out refresh
+ * tokens. Metadata supplied by the app takes precedence.
+ */
+const BROWSER_CLIENT_METADATA = {
+	token_endpoint_auth_method: 'none',
+	grant_types: ['authorization_code', 'refresh_token'],
+	response_types: ['code']
+}
+
+function sharedClientSetup(key, setup) {
+	if (!pendingClientSetups.has(key)) {
+		const pending = setup().finally(() => {
+			pendingClientSetups.delete(key)
+		})
+		pendingClientSetups.set(key, pending)
+	}
+	return pendingClientSetups.get(key)
+}
+
 export default function oidcmw(options={}) {
 
 	const defaultOptions = {
@@ -34,8 +58,18 @@ export default function oidcmw(options={}) {
 		openid_configuration: Optional()
 	})
 
+	// Discovery and client registration belong to the issuer. Tokens belong to
+	// the user they were issued for, so a login as one user can never reuse
+	// another user's tokens at the same issuer.
+	const account = accountFor(options)
+	const expectedClaims = expectedClaimsFor(options)
+	const site = siteFor(options.issuer, account)
+	const clientSetupKey = options.issuer + ' '
+		+ JSON.stringify(requestedClientInfo?.redirect_uris ?? null)
+	let userStore = options.store
 	if (!options.store) {
 		options.store = oidcStore(options.issuer)
+		userStore = oidcStore(site)
 	}
 	if (!options.openid_configuration && options.store.has('openid_configuration')) {
 		options.openid_configuration = options.store.get('openid_configuration')
@@ -47,56 +81,95 @@ export default function oidcmw(options={}) {
 		}
 	}
 
-	return async (req, next) => {
-		let res
-		if (!options.force_authorization) {
-			try {
-				res = await next(req)
-			} catch(err) {
-				res = err?.cause
-				if (!res || (res.status!=401 && res.status!=403)) {
-					throw err
-				}
-			}
-			if (res.ok || (res.status!=401 && res.status!=403)) {
-				return res
-			}
+	/**
+	 * Discovers the issuer and registers this client once. Concurrent requests
+	 * wait for the same registration, so tokens are never issued to one
+	 * registered client while another client_id is stored.
+	 */
+	async function prepareClient()
+	{
+		if (options.openid_configuration && options.client_info?.client_id) {
+			return
 		}
-		if (!options.openid_configuration) {
-			options.openid_configuration = await discover({
+		const prepared = await sharedClientSetup(clientSetupKey, discoverAndRegister)
+		options.openid_configuration = prepared.openid_configuration
+		options.client_info = prepared.client_info
+		options.store.set('openid_configuration', options.openid_configuration)
+		options.store.set('client_info', options.client_info)
+	}
+
+	async function discoverAndRegister()
+	{
+		let openid_configuration = options.openid_configuration
+		if (!openid_configuration) {
+			openid_configuration = await discover({
 				issuer: options.issuer,
 				client: options.client.with(options.issuer)
 			})
-			options.store.set('openid_configuration', options.openid_configuration)
 		}
-
-		if (!options.client_info?.client_id) {
-			if (!options.openid_configuration.registration_endpoint) {
+		let client_info = options.client_info
+		if (!client_info?.client_id) {
+			if (!openid_configuration.registration_endpoint) {
 				throw metro.metroError('metro.oidcmw: Error: issuer '+options.issuer+' does not support dynamic client registration, but you haven\'t specified a client_id')
 			}
-			options.client_info = await register({
-				registration_endpoint: options.openid_configuration.registration_endpoint,
+			client_info = await register({
+				registration_endpoint: openid_configuration.registration_endpoint,
 				client: options.client,
-				client_info: options.client_info
+				client_info: Object.assign({}, BROWSER_CLIENT_METADATA, client_info)
 			})
-			options.store.set('client_info', options.client_info)
+			if (client_info.token_endpoint_auth_method == 'none') {
+				// a public client has no use for a secret, so it is not stored
+				delete client_info.client_secret
+			}
+		}
+		return { openid_configuration, client_info }
+	}
+
+	/**
+	 * The id_token must carry the nonce of the authorization request that
+	 * produced it. Storing the nonce when that request starts means a request
+	 * waiting for someone else's login, or the first request after a redirect
+	 * back from the issuer, cannot replace it.
+	 */
+	function rememberNonce(authorizeCallback)
+	{
+		if (typeof authorizeCallback != 'function') {
+			return authorizeCallback
+		}
+		return async url => {
+			userStore.set('pending_nonce', url.searchParams.get('nonce'))
+			return authorizeCallback(url)
+		}
+	}
+
+	return async (req, next) => {
+		let res
+		if (!options.force_authorization) {
+			// Middleware that turns responses into errors or data, such as
+			// thrower and getdata, belongs outside oidcmw, so the status of the
+			// actual response is visible here.
+			res = await next(req)
+			if (res.ok || (res.status!=401 && res.status!=403)) {
+				return res
+			}
 		}
+		await prepareClient()
 
 		// now initialize an oauth2 client stack, using options.client as default
 		// with forceAuthentication: true
-		const scope = options.scope || 'openid'
+		const scope = options.scope || defaultScope(options)
 		const nonce = options.nonce || oauth2.generateCodeVerifier(32)
-		options.store.set('pending_nonce', nonce)
 
 		const oauth2Options = Object.assign(
 			{
-				site: options.issuer,
+				site,
 				client: options.client,
 				force_authorization: true,
-				authorize_callback: options.authorize_callback,
+				authorize_callback: rememberNonce(options.authorize_callback),
 				oauth2_configuration: {
 					client_id: options.client_info?.client_id,
 					client_secret: options.client_info?.client_secret,
+					token_endpoint_auth_method: options.client_info?.token_endpoint_auth_method,
 					grant_type: 'authorization_code',
 					response_type: 'code',
 					response_mode: 'query',
@@ -104,6 +177,11 @@ export default function oidcmw(options={}) {
 					token_endpoint: options.openid_configuration.token_endpoint,
 					scope, //FIXME: should only use scopes supported by server
 					redirect_uri: options.client_info.redirect_uris[0],
+					login_hint: options.login_hint ?? options.webid,
+					issuer: options.openid_configuration.issuer,
+					authorization_response_iss_parameter_supported:
+						options.openid_configuration.authorization_response_iss_parameter_supported,
+					token_type: options.use_dpop ? 'DPoP' : undefined,
 					nonce
 				}
 			}
@@ -118,7 +196,8 @@ export default function oidcmw(options={}) {
 				return res
 			}
 			const contentType = res.headers.get('content-type')
-			if (!contentType?.startsWith('application/json')) {
+			if (!res.ok || !contentType?.startsWith('application/json')) {
+				// oauth2mw reports the token endpoint's own error
 				return res
 			}
 
@@ -129,16 +208,25 @@ export default function oidcmw(options={}) {
 			}
 
 			const id_token = data?.id_token
+			const isRefresh = await grantTypeOf(req) == 'refresh_token'
+			if (isRefresh && !id_token) {
+				// a refresh response may omit the id_token; the stored one stays
+				return res
+			}
 			const jwks = await getJwks()
 			const validation = await validateIdToken(id_token, {
 				issuer: options.openid_configuration.issuer,
 				client_id: options.client_info.client_id,
 				jwks,
 				openid_configuration: options.openid_configuration,
-				nonce: options.store.get('pending_nonce')
+				nonce: isRefresh ? undefined : userStore.get('pending_nonce')
 			})
-			options.store.set('id_token', id_token)
-			options.store.set('id_token_claims', validation.claims)
+			if (isRefresh) {
+				assertSameUserAsLogin(validation.claims, userStore.get('id_token_claims'))
+			}
+			assertExpectedUser(validation.claims, expectedClaims)
+			userStore.set('id_token', id_token)
+			userStore.set('id_token_claims', validation.claims)
 			return res
 		}
 
@@ -156,7 +244,6 @@ export default function oidcmw(options={}) {
 		if (options.use_dpop) {
 			const dpopOptions = {
 				site: options.issuer,
-				authorization_endpoint: options.openid_configuration.authorization_endpoint,
 				token_endpoint: options.openid_configuration.token_endpoint,
 				dpop_signing_alg_values_supported: options.openid_configuration.dpop_signing_alg_values_supported
 			}
@@ -184,6 +271,83 @@ function clientInfoMatchesRequest(storedClientInfo, requestedClientInfo) {
 	return requestedClientInfo.redirect_uris.every(uri => storedRedirectUris.has(uri))
 }
 
+/**
+ * A WebID identifies the user when available (Solid-OIDC puts it in the
+ * webid claim); otherwise login_hint and expected_claims do.
+ */
+function accountFor(options) {
+	return options.webid ?? options.login_hint
+}
+
+function expectedClaimsFor(options) {
+	if (options.webid) {
+		return Object.assign({ webid: options.webid }, options.expected_claims)
+	}
+	return options.expected_claims || {}
+}
+
+/**
+ * Solid-OIDC issuers only include the webid claim when the webid scope is
+ * requested (Solid-OIDC section 7). It is requested when a WebID is given or
+ * the issuer lists it in scopes_supported, which marks a Solid-OIDC issuer.
+ */
+function defaultScope(options) {
+	const supported = options.openid_configuration?.scopes_supported
+	const solidIssuer = Array.isArray(supported) && supported.includes('webid')
+	if (options.webid || solidIssuer) {
+		return 'openid webid'
+	}
+	return 'openid'
+}
+
+function siteFor(issuer, account) {
+	if (!account) {
+		return issuer
+	}
+	return issuer + '|' + account
+}
+
+/**
+ * Refuses tokens issued for another user than the one requested, e.g. when
+ * the issuer still has a login session for a different account.
+ */
+function assertExpectedUser(claims, expectedClaims) {
+	for (const [name, expected] of Object.entries(expectedClaims)) {
+		const actual = claimValue(claims, name)
+		if (actual !== expected) {
+			throw metro.metroError('metro.oidcmw: id_token is for a different user: '
+				+ 'expected ' + name + ' ' + expected + ', got ' + actual)
+		}
+	}
+}
+
+async function grantTypeOf(req) {
+	const body = await req.clone().text()
+	return new URLSearchParams(body).get('grant_type')
+}
+
+/**
+ * An id_token from a refresh has no nonce of its own. It must describe the
+ * same login: same issuer (checked by validateIdToken) and same subject.
+ */
+function assertSameUserAsLogin(claims, loginClaims) {
+	if (loginClaims && claims.sub !== loginClaims.sub) {
+		throw metro.metroError('metro.oidcmw: refreshed id_token is for a different user: '
+			+ 'expected sub ' + loginClaims.sub + ', got ' + claims.sub)
+	}
+}
+
+/**
+ * Solid-OIDC issuers put the WebID in the webid claim; older issuers only
+ * use sub for it.
+ */
+function claimValue(claims, name) {
+	if (name == 'webid' && claims.webid === undefined) {
+		return claims.sub
+	}
+	return claims[name]
+}
+
 export function isRedirected() {
 	return oauth2.isRedirected()
 }
@@ -193,7 +357,7 @@ export function idToken(options) {
 		if (!options.issuer) {
 			throw metro.metroError('Must supply options.issuer or options.store to get the id_token')
 		}
-		options.store = oidcStore(options.issuer)
+		options.store = oidcStore(siteFor(options.issuer, accountFor(options)))
 	}
 	return options.store.get('id_token')
 }
@@ -203,7 +367,7 @@ export function idTokenClaims(options) {
 		if (!options.issuer) {
 			throw metro.metroError('Must supply options.issuer or options.store to get the id_token claims')
 		}
-		options.store = oidcStore(options.issuer)
+		options.store = oidcStore(siteFor(options.issuer, accountFor(options)))
 	}
 	return options.store.get('id_token_claims')
 }