auth0 3.0.0 → 3.1.0

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # Change Log
 
+## [v3.1.0](https://github.com/auth0/node-auth0/tree/v3.1.0) (2023-01-12)
+
+[Full Changelog](https://github.com/auth0/node-auth0/compare/v3.0.1...v3.1.0)
+
+**Added**
+
+- [SDK-3868] Add support for managing client credentials [\#774](https://github.com/auth0/node-auth0/pull/774) ([adamjmcgrath](https://github.com/adamjmcgrath))
+- [SDK-3856] Add `client_assertion` to authenticate clients [\#761](https://github.com/auth0/node-auth0/pull/761) ([adamjmcgrath](https://github.com/adamjmcgrath))
+
+## [v3.0.1](https://github.com/auth0/node-auth0/tree/v3.0.1) (2022-12-22)
+
+[Full Changelog](https://github.com/auth0/node-auth0/compare/v3.0.0...v3.0.1)
+
+**Fixed**
+
+- bump jwks-rsa [\#769](https://github.com/auth0/node-auth0/pull/769) ([adamjmcgrath](https://github.com/adamjmcgrath))
+
 ## [v3.0.0](https://github.com/auth0/node-auth0/tree/v3.0.0) (2022-12-22)
 
 [Full Changelog](https://github.com/auth0/node-auth0/compare/v2.44.1...v3.0.0)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "auth0",
-  "version": "3.0.0",
+  "version": "3.1.0",
   "description": "SDK for Auth0 API v2",
   "main": "src/index.js",
   "sideEffects": false,
@@ -36,10 +36,11 @@
     "axios": "^0.27.2",
     "form-data": "^3.0.1",
     "jsonwebtoken": "^9.0.0",
-    "jwks-rsa": "^1.12.1",
+    "jwks-rsa": "^3.0.0",
     "lru-memoizer": "^2.1.4",
     "rest-facade": "^1.16.3",
-    "retry": "^0.13.1"
+    "retry": "^0.13.1",
+    "uuid": "^9.0.0"
   },
   "devDependencies": {
     "chai": "^4.2.0",

package/src/auth/OAuthAuthenticator.js

@@ -3,6 +3,7 @@ const { ArgumentError } = require('rest-facade');
 const RestClient = require('rest-facade').Client;
 const { SanitizedError } = require('../errors');
 const OAUthWithIDTokenValidation = require('./OAUthWithIDTokenValidation');
+const { addClientAuthentication } = require('./clientAuthentication');
 
 function getParamsFromOptions(options) {
   const params = {};
@@ -31,6 +32,8 @@ class OAuthAuthenticator {
    * @param  {string}              options.domain                      AuthenticationClient server domain
    * @param  {string}              [options.clientId]                  Default client ID.
    * @param  {string}              [options.clientSecret]              Default client Secret.
+   * @param  {string}              [options.clientAssertionSigningKey] Private key used to sign the client assertion JWT.
+   * @param  {string}              [options.clientAssertionSigningAlg] Default 'RS256'.
    * @param  {boolean}             [options.__bypassIdTokenValidation] Whether the id_token should be validated or not
    */
   constructor(options) {
@@ -55,8 +58,22 @@ class OAuthAuthenticator {
 
     this.oauth = new RestClient(`${options.baseUrl}/oauth/:type`, clientOptions);
     this.oauthWithIDTokenValidation = new OAUthWithIDTokenValidation(this.oauth, options);
+    this.domain = options.domain;
     this.clientId = options.clientId;
     this.clientSecret = options.clientSecret;
+    this.clientAssertionSigningKey = options.clientAssertionSigningKey;
+    this.clientAssertionSigningAlg = options.clientAssertionSigningAlg;
+  }
+
+  _addClientAuthentication(payload, required) {
+    return addClientAuthentication({
+      payload,
+      required,
+      domain: this.domain,
+      clientSecret: this.clientSecret,
+      clientAssertionSigningKey: this.clientAssertionSigningKey,
+      clientAssertionSigningAlg: this.clientAssertionSigningAlg,
+    });
   }
 
   /**
@@ -173,12 +190,11 @@ class OAuthAuthenticator {
       throw new ArgumentError('Missing user data object');
     }
 
-    const data = {
+    const data = this._addClientAuthentication({
       client_id: this.clientId,
-      client_secret: this.clientSecret,
       grant_type: 'password',
       ...userData,
-    };
+    });
 
     if (typeof data.username !== 'string' || data.username.split().length === 0) {
       throw new ArgumentError('username field is required');
@@ -238,12 +254,11 @@ class OAuthAuthenticator {
       throw new ArgumentError('Missing data object');
     }
 
-    data = {
+    data = this._addClientAuthentication({
       client_id: this.clientId,
-      client_secret: this.clientSecret,
       grant_type: 'refresh_token',
       ...data,
-    };
+    });
 
     if (typeof data.refresh_token !== 'string' || data.refresh_token.split().length === 0) {
       throw new ArgumentError('refresh_token is required');
@@ -297,21 +312,19 @@ class OAuthAuthenticator {
       throw new ArgumentError('Missing options object');
     }
 
-    const data = {
-      grant_type: 'client_credentials',
-      client_id: this.clientId,
-      client_secret: this.clientSecret,
-      ...options,
-    };
+    const data = this._addClientAuthentication(
+      {
+        grant_type: 'client_credentials',
+        client_id: this.clientId,
+        ...options,
+      },
+      true
+    );
 
     if (!data.client_id || data.client_id.trim().length === 0) {
       throw new ArgumentError('client_id field is required');
     }
 
-    if (!data.client_secret || data.client_secret.trim().length === 0) {
-      throw new ArgumentError('client_secret field is required');
-    }
-
     const params = {
       type: 'token',
     };
@@ -361,12 +374,11 @@ class OAuthAuthenticator {
       throw new ArgumentError('Missing options object');
     }
 
-    const data = {
+    const data = this._addClientAuthentication({
       grant_type: 'authorization_code',
       client_id: this.clientId,
-      client_secret: this.clientSecret,
       ...options,
-    };
+    });
 
     if (!data.code || data.code.trim().length === 0) {
       throw new ArgumentError('code field is required');

package/src/auth/PasswordlessAuthenticator.js

@@ -1,6 +1,7 @@
 const { ArgumentError } = require('rest-facade');
 const RestClient = require('rest-facade').Client;
 const { sanitizeArguments } = require('../utils');
+const { addClientAuthentication } = require('./clientAuthentication');
 
 function getParamsFromOptions(options) {
   const params = {};
@@ -23,8 +24,11 @@ class PasswordlessAuthenticator {
   /**
    * @param  {object}              options            Authenticator options.
    * @param  {string}              options.baseUrl    The auth0 account URL.
+   * @param  {string}              [options.domain] Required if using clientAssertionSigningKey.
    * @param  {string}              [options.clientId] Default client ID.
    * @param  {string}              [options.clientSecret] Default client secret.
+   * @param  {string}              [options.clientAssertionSigningKey] Private key used to sign the client assertion JWT.
+   * @param  {string}              [options.clientAssertionSigningAlg] Default 'RS256'.
    * @param  {OAuthAuthenticator}  oauth              OAuthAuthenticator instance.
    */
   constructor(options, oauth) {
@@ -48,8 +52,22 @@ class PasswordlessAuthenticator {
 
     this.oauth = oauth;
     this.passwordless = new RestClient(`${options.baseUrl}/passwordless/start`, clientOptions);
+    this.domain = options.domain;
     this.clientId = options.clientId;
     this.clientSecret = options.clientSecret;
+    this.clientAssertionSigningKey = options.clientAssertionSigningKey;
+    this.clientAssertionSigningAlg = options.clientAssertionSigningAlg;
+  }
+
+  _addClientAuthentication(payload, required) {
+    return addClientAuthentication({
+      payload,
+      required,
+      domain: this.domain,
+      clientSecret: this.clientSecret,
+      clientAssertionSigningKey: this.clientAssertionSigningKey,
+      clientAssertionSigningAlg: this.clientAssertionSigningAlg,
+    });
   }
 
   /**
@@ -120,11 +138,10 @@ class PasswordlessAuthenticator {
       throw new ArgumentError('Missing user data object');
     }
 
-    const data = {
+    const data = this._addClientAuthentication({
       client_id: this.clientId,
-      client_secret: this.clientSecret,
       ...userData,
-    };
+    });
 
     if (typeof data.username !== 'string' || data.username.trim().length === 0) {
       throw new ArgumentError('username field (phone number) is required');
@@ -200,11 +217,10 @@ class PasswordlessAuthenticator {
    */
   sendEmail(userData, options, cb) {
     const { options: sanitizedOptions, cb: sanitizedCb } = sanitizeArguments(options, cb);
-    const data = {
+    const data = this._addClientAuthentication({
       client_id: this.clientId,
-      client_secret: this.clientSecret,
       ...userData,
-    };
+    });
     const params = getParamsFromOptions(sanitizedOptions);
 
     // Don't let the user override the connection nor the grant type.
@@ -257,11 +273,10 @@ class PasswordlessAuthenticator {
    */
   sendSMS(userData, options, cb) {
     const { options: sanitizedOptions, cb: sanitizedCb } = sanitizeArguments(options, cb);
-    const data = {
+    const data = this._addClientAuthentication({
       client_id: this.clientId,
-      client_secret: this.clientSecret,
       ...userData,
-    };
+    });
     const params = getParamsFromOptions(sanitizedOptions);
 
     // Don't let the user override the connection nor the grant type.

package/src/auth/TokensManager.js

@@ -1,5 +1,6 @@
 const axios = require('axios');
 const { ArgumentError } = require('rest-facade');
+const { addClientAuthentication } = require('./clientAuthentication');
 
 /**
  * Provides methods for getting token data and exchanging tokens.
@@ -9,8 +10,11 @@ class TokensManager {
    * @param  {object}   options                 Manager options.
    * @param  {string}   options.baseUrl         The auth0 account URL.
    * @param  {string}   [options.headers]       Default request headers.
+   * @param  {string}   [options.domain]  Required if using clientAssertionSigningKey.
    * @param  {string}   [options.clientId]      Default client ID.
    * @param  {string}   [options.clientSecret]  Default client Secret.
+   * @param  {string}   [options.clientAssertionSigningKey]  Private key used to sign the client assertion JWT.
+   * @param  {string}   [options.clientAssertionSigningAlg]  Default 'RS256'.
    */
   constructor(options) {
     if (typeof options !== 'object') {
@@ -23,8 +27,11 @@ class TokensManager {
 
     this.baseUrl = options.baseUrl;
     this.headers = options.headers || {};
+    this.domain = options.domain;
     this.clientId = options.clientId || '';
     this.clientSecret = options.clientSecret || '';
+    this.clientAssertionSigningKey = options.clientAssertionSigningKey;
+    this.clientAssertionSigningAlg = options.clientAssertionSigningAlg;
   }
 
   /**
@@ -213,11 +220,16 @@ class TokensManager {
       );
     }
 
-    const body = {
-      client_id: this.clientId,
-      client_secret: this.clientSecret,
-      ...data,
-    };
+    const body = addClientAuthentication({
+      payload: {
+        client_id: this.clientId,
+        ...data,
+      },
+      domain: this.domain,
+      clientSecret: this.clientSecret,
+      clientAssertionSigningKey: this.clientAssertionSigningKey,
+      clientAssertionSigningAlg: this.clientAssertionSigningAlg,
+    });
 
     const { headers } = this;
 

package/src/auth/clientAuthentication.js

@@ -0,0 +1,86 @@
+const { ArgumentError } = require('rest-facade');
+const jwt = require('jsonwebtoken');
+const uuid = require('uuid');
+
+/**
+ * Create a JWT signed with the clientAssertionSigningKey
+ * for use on clients with token endpoint auth method of private_key_jwt.
+ *
+ * @param {string} domain The domain of the Authorization Server (can be a custom domain).
+ * @param {string} clientId The Client ID.
+ * @param {string} clientAssertionSigningKey A private key in PEM format to sign the client assertion JWT.
+ * @param {string} clientAssertionSigningAlg The alg to use to sign the JWT (default RS256)
+ * @returns {string} A JWT.
+ */
+const createClientAssertionJWT = ({
+  clientId,
+  clientAssertionSigningKey,
+  clientAssertionSigningAlg,
+  domain,
+}) => {
+  const now = Math.floor(Date.now() / 1000);
+  const payload = {
+    iss: clientId,
+    sub: clientId,
+    aud: `https://${domain}/`,
+    iat: now,
+    exp: now + 180,
+    jti: uuid.v4(),
+  };
+  return jwt.sign(payload, clientAssertionSigningKey, {
+    algorithm: clientAssertionSigningAlg || 'RS256',
+  });
+};
+
+/**
+ * Adds client authentication, if available, to the payload of the following requests:
+ * - /oauth/token
+ * - /oauth/revoke
+ * - /mfa/associate
+ * - /mfa/challenge
+ * - /passwordless/start
+ *
+ * Adds `client_secret` for Client Secret Post token endpoint auth method (the SDK doesn't use Client Secret Basic)
+ * Adds `client_assertion` and `client_assertion_type` for Private Key JWT token endpoint auth method.
+ *
+ * If `clientAssertionSigningKey` is provided it takes precedent over `clientSecret` .
+ *
+ * @param {object} payload The body of the request to be authenticated.
+ * @param {string} domain The domain of the Authorization Server (can be a custom domain).
+ * @param {boolean} [required] True if client authentication is required.
+ * @param {string} [clientAssertionSigningKey] A private key in PEM format to sign the client assertion JWT.
+ * @param {string} clientAssertionSigningAlg The alg to use to sign the JWT (default RS256)
+ * @param {string} [clientSecret] The client secret.
+ * @returns {object} The payload with additional fields for client authentication.
+ */
+const addClientAuthentication = ({
+  payload,
+  domain,
+  required,
+  clientAssertionSigningKey,
+  clientAssertionSigningAlg,
+  clientSecret,
+}) => {
+  const clientId = payload.client_id;
+  if (clientAssertionSigningKey && !payload.client_assertion) {
+    payload.client_assertion = createClientAssertionJWT({
+      clientId,
+      clientAssertionSigningKey,
+      clientAssertionSigningAlg,
+      domain,
+    });
+    payload.client_assertion_type = 'urn:ietf:params:oauth:client-assertion-type:jwt-bearer';
+  } else if (clientSecret && !payload.client_secret) {
+    payload.client_secret = clientSecret;
+  }
+  if (
+    required &&
+    (!payload.client_secret || payload.client_secret.trim().length === 0) &&
+    (!payload.client_assertion || payload.client_assertion.trim().length === 0)
+  ) {
+    throw new ArgumentError('The client_secret or client_assertion field is required.');
+  }
+  return payload;
+};
+
+module.exports.addClientAuthentication = addClientAuthentication;

package/src/auth/index.js

@@ -37,6 +37,8 @@ class AuthenticationClient {
    * @param   {string}  options.domain                    AuthenticationClient server domain.
    * @param   {string}  [options.clientId]                Default client ID.
    * @param   {string}  [options.clientSecret]            Default client Secret.
+   * @param   {string}  [options.clientAssertionSigningKey] Private key used to sign the client assertion JWT.
+   * @param   {string}  [options.clientAssertionSigningAlg] Default RS256
    * @param   {string}  [options.supportedAlgorithms]     Algorithms that your application expects to receive
    * @param  {boolean}  [options.__bypassIdTokenValidation] Whether the id_token should be validated or not
    * @param   {object}  [options.headers]                 Additional headers that will be added to the outgoing requests.
@@ -59,6 +61,8 @@ class AuthenticationClient {
       clientId: options.clientId,
       domain: options.domain,
       clientSecret: options.clientSecret,
+      clientAssertionSigningKey: options.clientAssertionSigningKey,
+      clientAssertionSigningAlg: options.clientAssertionSigningAlg,
       headers: Object.assign(defaultHeaders, options.headers || {}),
       baseUrl: util.format(BASE_URL_FORMAT, options.domain),
       supportedAlgorithms: options.supportedAlgorithms,

package/src/management/ClientCredentialsManager.js

@@ -0,0 +1,112 @@
+const BaseManager = require('./BaseManager');
+
+/**
+ * The client credentials class provides a simple abstraction for performing CRUD operations
+ * on Auth0 ClientCredentials.
+ */
+class ClientCredentialsManager extends BaseManager {
+  /**
+   * @param {object} options            The client options.
+   * @param {string} options.baseUrl    The URL of the API.
+   * @param {object} [options.headers]  Headers to be included in all requests.
+   * @param {object} [options.retry]    Retry Policy Config
+   */
+  constructor(options) {
+    super(options);
+
+    /**
+     * @type {external:RestClient}
+     */
+    this.resource = this._getRestClient('/clients/:client_id/credentials/:credential_id');
+  }
+
+  /**
+   * Create a new client credential.
+   *
+   * @example
+   * var params = { client_id: CLIENT_ID };
+   *
+   * management.clientCredentials.create(params, data, function (err, credential) {
+   *   if (err) {
+   *     // Handle error.
+   *   }
+   *
+   *   // The credential created.
+   *   console.log({credential});
+   * });
+   * @param   {string}    params.client_id   The client id.
+   * @param   {object}    data               Client Credential data object.
+   * @param   {Function}  [cb]               Callback function.
+   * @returns  {Promise|undefined}
+   */
+  create(...args) {
+    return this.resource.create(...args);
+  }
+
+  /**
+   * Return a list of credentials for a given client.
+   *
+   * @example
+   * var params = { client_id: CLIENT_ID };
+   *
+   * management.clientCredentials.getAll(params, function (err, credentials) {
+   *   if (err) {
+   *     // Handle error.
+   *   }
+   *
+   *   // A list of credentials associated with that client.
+   *   console.log({credentials});
+   * });
+   * @param   {string}    params.client_id   The client id.
+   * @param   {Function}  [cb]               Callback function.
+   * @returns  {Promise|undefined}
+   */
+  getAll(...args) {
+    return this.resource.getAll(...args);
+  }
+
+  /**
+   * Return a credential for a given client.
+   *
+   * @example
+   * var params = { client_id: CLIENT_ID, credential_id: CREDENTIAL_ID };
+   *
+   * management.clientCredentials.getById(data, function (err, credential) {
+   *   if (err) {
+   *     // Handle error.
+   *   }
+   *
+   *   // A specific credential associated with that credential.
+   *   console.log({credential});
+   * });
+   * @param   {string}    params.client_id      The client id.
+   * @param   {string}    params.credential_id  The credential id.
+   * @param   {Function}  [cb]                  Callback function.
+   * @returns  {Promise|undefined}
+   */
+  get(...args) {
+    return this.resource.get(...args);
+  }
+
+  /**
+   * Delete a credential for a given client.
+   *
+   * @example
+   * var params = { client_id: CLIENT_ID, credential_id: CREDENTIAL_ID };
+   *
+   * management.clientCredentials.delete(params, data, function (err) {
+   *   if (err) {
+   *     // Handle error.
+   *   }
+   * });
+   * @param   {string}    params.client_id      The client id.
+   * @param   {string}    params.credential_id  The credential id.
+   * @param   {Function}  [cb]                  Callback function.
+   * @returns  {Promise|undefined}
+   */
+  delete(...args) {
+    return this.resource.delete(...args);
+  }
+}
+
+module.exports = ClientCredentialsManager;

package/src/management/ManagementTokenProvider.js

@@ -12,6 +12,8 @@ class ManagementTokenProvider {
    * @param {string}  options.domain                  ManagementClient server domain.
    * @param {string}  options.clientId                Non Interactive Client Id.
    * @param {string}  options.clientSecret            Non Interactive Client Secret.
+   * @param {string}  options.clientAssertionSigningKey Private key used to sign the client assertion JWT.
+   * @param {string}  options.clientAssertionSigningAlg Default 'RS256'.
    * @param {string}  options.scope                   Non Interactive Client Scope.
    * @param {string}  options.audience                Audience of the Management API.
    * @param {boolean} [options.enableCache=true]      Enabled or Disable Cache
@@ -33,8 +35,11 @@ class ManagementTokenProvider {
       throw new ArgumentError('Must provide a clientId');
     }
 
-    if (!params.clientSecret || params.clientSecret.length === 0) {
-      throw new ArgumentError('Must provide a clientSecret');
+    if (
+      (!params.clientSecret || params.clientSecret.length === 0) &&
+      (!params.clientAssertionSigningKey || params.clientAssertionSigningKey.length === 0)
+    ) {
+      throw new ArgumentError('Must provide a clientSecret or a clientAssertionSigningKey');
     }
 
     if (!params.audience || params.audience.length === 0) {
@@ -64,6 +69,8 @@ class ManagementTokenProvider {
       domain: this.options.domain,
       clientId: this.options.clientId,
       clientSecret: this.options.clientSecret,
+      clientAssertionSigningKey: this.options.clientAssertionSigningKey,
+      clientAssertionSigningAlg: this.options.clientAssertionSigningAlg,
       telemetry: this.options.telemetry,
       clientInfo: this.options.clientInfo,
       headers: this.options.headers,

package/src/management/index.js

@@ -4,6 +4,7 @@ const { jsonToBase64, generateClientInfo } = utils;
 const { ArgumentError } = require('rest-facade');
 
 // Managers.
+const ClientCredentialsManager = require('./ClientCredentialsManager');
 const ClientsManager = require('./ClientsManager');
 const ClientGrantsManager = require('./ClientGrantsManager');
 const GrantsManager = require('./GrantsManager');
@@ -73,16 +74,32 @@ const MANAGEMENT_API_AUD_FORMAT = 'https://%s/api/v2/';
  *    cacheTTLInSeconds: 10
  *  }
  * });
+ * @example <caption>
+ *   Initialize your client class, by using a Non Interactive Client to fetch an access_token
+ *   via the Client Credentials Grant, providing a Private Key using the private_key_jwt token
+ *   endpoint auth method.
+ * </caption>
+ *
+ * var ManagementClient = require('auth0').ManagementClient;
+ * var auth0 = new ManagementClient({
+ *   domain: '{YOUR_ACCOUNT}.auth0.com',
+ *   clientId: '{YOUR_NON_INTERACTIVE_CLIENT_ID}',
+ *   clientAssertionSigningKey: fs.readFileSync('private-key.pem'),
+ *   scope: "read:users write:users"
+ * });
  */
 class ManagementClient {
   /**
    * @param   {object}  options                                   Options for the ManagementClient SDK.
    *          If a token is provided only the domain is required, other parameters are ignored.
-   *          If no token is provided domain, clientId, clientSecret and scopes are required
+   *          If no token is provided domain, clientId, clientSecret (or clientAssertionSigningKey)
+   *          and scopes are required
    * @param   {string}  options.domain                              ManagementClient server domain.
    * @param   {string}  [options.token]                             API access token.
    * @param   {string}  [options.clientId]                          Management API Non Interactive Client Id.
    * @param   {string}  [options.clientSecret]                      Management API Non Interactive Client Secret.
+   * @param   {string}  [options.clientAssertionSigningKey]         Private key used to sign the client assertion JWT.
+   * @param   {string}  [options.clientAssertionSigningAlg]         Default 'RS256'.
    * @param   {string}  [options.audience]                          Management API Audience. By default is your domain's, e.g. the domain is `tenant.auth0.com` and the audience is `http://tenant.auth0.com/api/v2/`
    * @param   {string}  [options.scope]                             Management API Scopes.
    * @param   {boolean} [options.tokenProvider.enableCache=true]    Enabled or Disable Cache.
@@ -160,6 +177,14 @@ class ManagementClient {
      */
     this.clients = new ClientsManager(managerOptions);
 
+    /**
+     * Simple abstraction for performing CRUD operations on the
+     * client credentials endpoint.
+     *
+     * @type {module:management.ClientCredentialsManager}
+     */
+    this.clientCredentials = new ClientCredentialsManager(managerOptions);
+
     /**
      * Simple abstraction for performing CRUD operations on the client grants
      * endpoint.