feat: JWT Response for OAuth Token Introspection

As defined by https://tools.ietf.org/html/draft-lodderstedt-oauth-jwt-introspection-response
this allows for introspection response to be a JWT

Enable by configuration = { features: { introspection: true, jwtIntrospection: true } }

New client properties:
- introspection_signed_response_alg

if encryption is also enabled
- introspection_encrypted_response_alg
- introspection_encrypted_response_enc

Author: panva

README.md

@@ -52,6 +52,7 @@ The following drafts/experimental specifications are implemented by oidc-provide
 - [RFC7592 - OAuth 2.0 Dynamic Client Registration Management Protocol (Update and Delete)][registration-management]
 - [OAuth 2.0 Web Message Response Mode - draft 00][wmrm]
 - [OAuth 2.0 Device Flow for Browserless and Input Constrained Devices - draft 11][device-flow]
+- [JWT Response for OAuth Token Introspection - draft 01][jwt-introspection]
 
 Updates to draft and experimental specification versions are released as MINOR library versions,
 if you utilize these specification implementations consider using the tilde `~` operator in your
@@ -171,3 +172,4 @@ See the list of available emitted [event names](/docs/events.md) and their descr
 [debug-link]: https://github.com/visionmedia/debug
 [wmrm]: https://tools.ietf.org/html/draft-sakimura-oauth-wmrm-00
 [device-flow]: https://tools.ietf.org/html/draft-ietf-oauth-device-flow-11
+[jwt-introspection]: https://tools.ietf.org/html/draft-lodderstedt-oauth-jwt-introspection-response-01

docs/configuration.md

@@ -368,6 +368,7 @@ deployment compact. The feature flags with their default values are
 | encryption | no |
 | frontchannelLogout | no |
 | introspection | no |
+| jwtIntrospection | no |
 | oauthNativeApps | yes (forces pkce on with forcedForNative) |
 | pkce | yes |
 | registration | no |
@@ -499,6 +500,7 @@ introspection_endpoint property of the discovery endpoint is published, otherwis
 is not sent. The use of this endpoint is covered by the same authz mechanism as the regular token
 endpoint or `introspection_endpoint_auth_method` and `introspection_endpoint_auth_signing_alg` if
 defined on a client.
+
 ```js
 const configuration = { features: { introspection: Boolean[false] } };
 ```
@@ -508,6 +510,14 @@ the token endpoint access must be authorized it is recommended to setup a client
 use. This client should be unusable for standard authorization flow, to set up such a client provide
 grant_types, response_types and redirect_uris as empty arrays.
 
+**JWT Response for OAuth Token Introspection**
+Enables additional JSON Web Token responses for OAuth 2.0 Token Introspection as defined by
+[JWT Response for OAuth Token Introspection - draft 01][jwt-introspection]
+
+```js
+const configuration = { features: { introspection: true, jwtIntrospection: Boolean[false] } };
+```
+
 
 **Revocation endpoint**  
 Enables the use of Revocation endpoint as described in [RFC7009][revocation] for tokens of
@@ -1187,6 +1197,7 @@ _**default value**_:
   encryption: false,
   frontchannelLogout: false,
   introspection: false,
+  jwtIntrospection: false,
   registration: false,
   registrationManagement: false,
   request: false,
@@ -1597,7 +1608,10 @@ _**default value**_:
   revocationEndpointAuthSigningAlgValues: [],
   userinfoEncryptionAlgValues: [],
   userinfoEncryptionEncValues: [],
-  userinfoSigningAlgValues: [] }
+  userinfoSigningAlgValues: [],
+  introspectionEncryptionAlgValues: [],
+  introspectionEncryptionEncValues: [],
+  introspectionSigningAlgValues: [] }
 ```
 
 ### userCodeConfirmSource
@@ -1707,3 +1721,4 @@ async userCodeInputSource(ctx, form, out, err) {
 [third-party-cookies-so]: https://stackoverflow.com/questions/3550790/check-if-third-party-cookies-are-enabled/7104048#7104048
 [wmrm]: https://tools.ietf.org/html/draft-sakimura-oauth-wmrm-00
 [device-flow]: https://tools.ietf.org/html/draft-ietf-oauth-device-flow-11
+[jwt-introspection]: https://tools.ietf.org/html/draft-lodderstedt-oauth-jwt-introspection-response-01

example/settings.js

@@ -36,6 +36,7 @@ module.exports.config = {
     encryption: true, // defaults to false
     frontchannelLogout: true, // defaults to false
     introspection: true, // defaults to false
+    jwtIntrospection: true, // defaults to false
     registration: true, // defaults to false
     request: true, // defaults to false
     revocation: true, // defaults to false

lib/actions/discovery.js

@@ -1,3 +1,5 @@
+/* eslint-disable max-len */
+
 const { defaults } = require('lodash');
 
 const instance = require('../helpers/weak_cache');
@@ -15,20 +17,12 @@ module.exports = function discoveryAction(provider) {
       id_token_signing_alg_values_supported: config.idTokenSigningAlgValues,
       issuer: provider.issuer,
       jwks_uri: ctx.oidc.urlFor('certificates'),
-      registration_endpoint: config.features.registration
-        ? ctx.oidc.urlFor('registration') : undefined,
-      request_object_signing_alg_values_supported:
-        config.features.request || config.features.requestUri
-          ? config.requestObjectSigningAlgValues : undefined,
+      registration_endpoint: config.features.registration ? ctx.oidc.urlFor('registration') : undefined,
+      request_object_signing_alg_values_supported: config.features.request || config.features.requestUri ? config.requestObjectSigningAlgValues : undefined,
       request_parameter_supported: !!config.features.request,
       request_uri_parameter_supported: !!config.features.requestUri,
-      require_request_uri_registration: config.features.requestUri
-        && config.features.requestUri.requireRequestUriRegistration ? true : undefined,
-      response_modes_supported: [
-        'form_post',
-        'fragment',
-        'query',
-      ],
+      require_request_uri_registration: config.features.requestUri && config.features.requestUri.requireRequestUriRegistration ? true : undefined,
+      response_modes_supported: ['form_post', 'fragment', 'query'],
       response_types_supported: config.responseTypes,
       scopes_supported: config.scopes,
       subject_types_supported: config.subjectTypes,
@@ -37,26 +31,27 @@ module.exports = function discoveryAction(provider) {
       token_endpoint_auth_signing_alg_values_supported: config.tokenEndpointAuthSigningAlgValues,
       userinfo_endpoint: ctx.oidc.urlFor('userinfo'),
       userinfo_signing_alg_values_supported: config.userinfoSigningAlgValues,
-      code_challenge_methods_supported: config.features.pkce
-        ? config.features.pkce.supportedMethods : undefined,
+      code_challenge_methods_supported: config.features.pkce ? config.features.pkce.supportedMethods : undefined,
     };
 
     if (config.features.webMessageResponseMode) {
       ctx.body.response_modes_supported.push('web_message');
     }
 
     if (config.features.introspection) {
-      const prefix = 'introspection_endpoint';
       ctx.body.introspection_endpoint = ctx.oidc.urlFor('introspection');
-      ctx.body[`${prefix}_auth_methods_supported`] = config.introspectionEndpointAuthMethods;
-      ctx.body[`${prefix}_auth_signing_alg_values_supported`] = config.introspectionEndpointAuthSigningAlgValues;
+      ctx.body.introspection_endpoint_auth_methods_supported = config.introspectionEndpointAuthMethods;
+      ctx.body.introspection_endpoint_auth_signing_alg_values_supported = config.introspectionEndpointAuthSigningAlgValues;
+    }
+
+    if (config.features.jwtIntrospection) {
+      ctx.body.introspection_endpoint_signing_alg_values_supported = config.introspectionSigningAlgValues;
     }
 
     if (config.features.revocation) {
-      const prefix = 'revocation_endpoint';
       ctx.body.revocation_endpoint = ctx.oidc.urlFor('revocation');
-      ctx.body[`${prefix}_auth_methods_supported`] = config.revocationEndpointAuthMethods;
-      ctx.body[`${prefix}_auth_signing_alg_values_supported`] = config.revocationEndpointAuthSigningAlgValues;
+      ctx.body.revocation_endpoint_auth_methods_supported = config.revocationEndpointAuthMethods;
+      ctx.body.revocation_endpoint_auth_signing_alg_values_supported = config.revocationEndpointAuthSigningAlgValues;
     }
 
     if (config.features.encryption) {
@@ -65,10 +60,14 @@ module.exports = function discoveryAction(provider) {
       ctx.body.userinfo_encryption_alg_values_supported = config.userinfoEncryptionAlgValues;
       ctx.body.userinfo_encryption_enc_values_supported = config.userinfoEncryptionEncValues;
 
+      if (config.features.jwtIntrospection) {
+        ctx.body.introspection_encryption_alg_values_supported = config.introspectionEncryptionAlgValues;
+        ctx.body.introspection_encryption_enc_values_supported = config.introspectionEncryptionEncValues;
+      }
+
       if (config.features.request || config.features.requestUri) {
-        const prefix = 'request_object_encryption';
-        ctx.body[`${prefix}_alg_values_supported`] = config.requestObjectEncryptionAlgValues;
-        ctx.body[`${prefix}_enc_values_supported`] = config.requestObjectEncryptionEncValues;
+        ctx.body.request_object_encryption_alg_values_supported = config.requestObjectEncryptionAlgValues;
+        ctx.body.request_object_encryption_enc_values_supported = config.requestObjectEncryptionEncValues;
       }
     }
 

lib/actions/introspection.js

@@ -11,30 +11,37 @@ const instance = require('../helpers/weak_cache');
 const bodyParser = require('../shared/selective_body');
 const rejectDupes = require('../shared/reject_dupes');
 const getParams = require('../shared/assemble_params');
+const { InvalidRequest } = require('../helpers/errors');
 
 const introspectable = new Set(['AccessToken', 'ClientCredentials', 'RefreshToken']);
 const PARAM_LIST = new Set(['token', 'token_type_hint', ...tokenAuth.AUTH_PARAMS]);
+const JWT = 'application/jwt';
 
 module.exports = function introspectionAction(provider) {
-  const Claims = mask(instance(provider).configuration());
+  const configuration = instance(provider).configuration();
+  const { features: { jwtIntrospection } } = configuration;
+  const Claims = mask(configuration);
   const parseBody = bodyParser('application/x-www-form-urlencoded');
   const buildParams = getParams(PARAM_LIST);
   const { grantTypeHandlers } = instance(provider);
+  const {
+    IdToken, AccessToken, ClientCredentials, RefreshToken, Client,
+  } = provider;
 
   function getAccessToken(token) {
-    return provider.AccessToken.find(token);
+    return AccessToken.find(token);
   }
 
   function getClientCredentials(token) {
     /* istanbul ignore if */
     if (!grantTypeHandlers.has('client_credentials')) return undefined;
-    return provider.ClientCredentials.find(token);
+    return ClientCredentials.find(token);
   }
 
   function getRefreshToken(token) {
     /* istanbul ignore if */
     if (!grantTypeHandlers.has('refresh_token')) return undefined;
-    return provider.RefreshToken.find(token);
+    return RefreshToken.find(token);
   }
 
   function findResult(results) {
@@ -63,6 +70,34 @@ module.exports = function introspectionAction(provider) {
       );
     },
 
+    async function jwtIntrospectionResponse(ctx, next) {
+      if (jwtIntrospection) {
+        const { client } = ctx.oidc;
+
+        const {
+          introspectionEncryptedResponseAlg: encrypt,
+          introspectionSignedResponseAlg: sign,
+          introspectionEndpointAuthMethod: method,
+        } = client;
+
+        if (encrypt && method === 'none' && ctx.accepts('json', JWT) !== JWT) {
+          throw new InvalidRequest(`introspection must be requested with Accept: ${JWT} for this client`);
+        }
+
+        await next();
+
+        if ((encrypt || sign) && ctx.accepts('json', JWT) === JWT) {
+          const token = new IdToken({});
+          token.extra = ctx.body;
+
+          ctx.body = await token.sign(client, { use: 'introspection' });
+          ctx.type = 'application/jwt; charset=utf-8';
+        }
+      } else {
+        await next();
+      }
+    },
+
     async function renderTokenResponse(ctx, next) {
       const { params } = ctx.oidc;
 
@@ -132,7 +167,7 @@ module.exports = function introspectionAction(provider) {
       if (token.clientId !== ctx.oidc.client.clientId) {
         ctx.body.sub = Claims.sub(
           token.accountId,
-          (await provider.Client.find(token.clientId)).sectorIdentifier,
+          (await Client.find(token.clientId)).sectorIdentifier,
         );
       } else {
         ctx.body.sub = Claims.sub(token.accountId, ctx.oidc.client.sectorIdentifier);

lib/consts/client_attributes.js

@@ -42,6 +42,7 @@ const SECRET_LENGTH_REQUIRED = [
   'request_object_signing_alg',
   'token_endpoint_auth_signing_alg',
   'userinfo_signed_response_alg',
+  'introspection_signed_response_alg',
 
   // must be after token_endpoint_auth_signing_alg
   'introspection_endpoint_auth_signing_alg',
@@ -96,6 +97,9 @@ const STRING = [
   'userinfo_encrypted_response_alg',
   'userinfo_encrypted_response_enc',
   'userinfo_signed_response_alg',
+  'introspection_encrypted_response_alg',
+  'introspection_encrypted_response_enc',
+  'introspection_signed_response_alg',
 
   // must be after token_endpoint_auth_method
   'introspection_endpoint_auth_method',
@@ -116,6 +120,7 @@ const WHEN = {
   id_token_encrypted_response_enc: ['id_token_encrypted_response_alg', 'A128CBC-HS256'],
   request_object_encryption_enc: ['request_object_encryption_alg', 'A128CBC-HS256'],
   userinfo_encrypted_response_enc: ['userinfo_encrypted_response_alg', 'A128CBC-HS256'],
+  introspection_encrypted_response_enc: ['introspection_encrypted_response_alg', 'A128CBC-HS256'],
 };
 
 const WEB_URI = [

lib/helpers/client_schema.js

@@ -44,6 +44,15 @@ module.exports = function getSchema(provider) {
   if (features.introspection) {
     RECOGNIZED_METADATA.push('introspection_endpoint_auth_method');
     RECOGNIZED_METADATA.push('introspection_endpoint_auth_signing_alg');
+
+    if (features.jwtIntrospection) {
+      RECOGNIZED_METADATA.push('introspection_signed_response_alg');
+
+      if (features.encryption) {
+        RECOGNIZED_METADATA.push('introspection_encrypted_response_alg');
+        RECOGNIZED_METADATA.push('introspection_encrypted_response_enc');
+      }
+    }
   }
 
   if (features.revocation) {
@@ -121,6 +130,9 @@ module.exports = function getSchema(provider) {
     userinfo_encrypted_response_alg: () => configuration.userinfoEncryptionAlgValues,
     userinfo_encrypted_response_enc: () => configuration.userinfoEncryptionEncValues,
     userinfo_signed_response_alg: () => configuration.userinfoSigningAlgValues,
+    introspection_encrypted_response_alg: () => configuration.introspectionEncryptionAlgValues,
+    introspection_encrypted_response_enc: () => configuration.introspectionEncryptionEncValues,
+    introspection_signed_response_alg: () => configuration.introspectionSigningAlgValues,
 
     // must be after token_* specific
     introspection_endpoint_auth_method: () => configuration.introspectionEndpointAuthMethods,
@@ -131,6 +143,9 @@ module.exports = function getSchema(provider) {
       () => configuration.revocationEndpointAuthSigningAlgValues,
   };
 
+  const requestSignAlgRequiringJwks = /^(RS|ES)/;
+  const encAlgRequiringJwks = /^(RSA|ECDH)/;
+
   class Schema {
     constructor(metadata) {
       // unless explicitly provided use token_* values
@@ -251,9 +266,10 @@ module.exports = function getSchema(provider) {
       const requireJwks = this.token_endpoint_auth_method === 'private_key_jwt'
         || this.introspection_endpoint_auth_method === 'private_key_jwt'
         || this.revocation_endpoint_auth_method === 'private_key_jwt'
-        || (String(this.request_object_signing_alg).match(/^(RS|ES)/))
-        || (String(this.id_token_encrypted_response_alg).match(/^(RSA|ECDH)/))
-        || (String(this.userinfo_encrypted_response_alg).match(/^(RSA|ECDH)/));
+        || (requestSignAlgRequiringJwks.exec(this.request_object_signing_alg))
+        || (encAlgRequiringJwks.exec(this.id_token_encrypted_response_alg))
+        || (encAlgRequiringJwks.exec(this.userinfo_encrypted_response_alg))
+        || (encAlgRequiringJwks.exec(this.introspection_encrypted_response_alg));
 
       if (requireJwks && !this.jwks && !this.jwks_uri) {
         invalidate('jwks or jwks_uri is mandatory for this client');

lib/helpers/configuration.js

@@ -66,6 +66,12 @@ class Configuration {
       }
     }
 
+    if (!this.features.introspection) {
+      if (this.features.jwtIntrospection) {
+        throw new Error('jwtIntrospection is only available in conjuction with introspection');
+      }
+    }
+
     if (this.features.registrationManagement && !this.features.registration) {
       throw new Error('registrationManagement is only available in conjuction with registration');
     }

lib/helpers/configuration_schema.js

@@ -213,6 +213,10 @@ module.exports = class ConfigurationSchema {
     this.userinfoEncryptionAlgValues = fullEncAlg.slice();
     this.userinfoEncryptionEncValues = this.features.encryption ? encryptionEnc.slice() : [];
     this.userinfoSigningAlgValues = secretSig.slice();
+
+    this.introspectionEncryptionAlgValues = fullEncAlg.slice();
+    this.introspectionEncryptionEncValues = this.features.encryption ? encryptionEnc.slice() : [];
+    this.introspectionSigningAlgValues = secretSig.slice();
   }
 
   endpointAuth(endpoint) {
@@ -247,5 +251,8 @@ module.exports = class ConfigurationSchema {
     this.omitUnsupported('userinfoEncryptionAlgValues');
     this.omitUnsupported('userinfoEncryptionEncValues');
     this.omitUnsupported('userinfoSigningAlgValues');
+    this.omitUnsupported('introspectionEncryptionAlgValues');
+    this.omitUnsupported('introspectionEncryptionEncValues');
+    this.omitUnsupported('introspectionSigningAlgValues');
   }
 };

lib/helpers/defaults.js

@@ -182,6 +182,7 @@ const DEFAULTS = {
     encryption: false,
     frontchannelLogout: false,
     introspection: false,
+    jwtIntrospection: false,
     registration: false,
     registrationManagement: false,
     request: false,
@@ -749,6 +750,9 @@ const DEFAULTS = {
     userinfoEncryptionAlgValues: [],
     userinfoEncryptionEncValues: [],
     userinfoSigningAlgValues: [],
+    introspectionEncryptionAlgValues: [],
+    introspectionEncryptionEncValues: [],
+    introspectionSigningAlgValues: [],
   },