auth0-ext v7.0.5

auth0-ext

Common extensibility code

Installation

npm i auth0/auth0-ext --save

Usage

var auth0ext = require('auth0-ext');
var run_in_sandbox = auth0ext.sandboxes.initialize(mode, {
  get_env: function (key) {
    return nconf.get(key);
  }
});

The get_env function is used to read the configuration from the underlying application. The keys need

Example of keys that will be read:

  "SANDBOX_MODE": "auth0-sandbox"
  "DEFAULT_AUTH0_SANDBOX_URL": "https://sandbox.it.auth0.com"
  "DEFAULT_AUTH0_SANDBOX_KEY": "eyJhbGciOiJIUzI1NiIsImtpZCI6Ij...."
  "DEFAULT_AUTH0_SANDBOX_CA": ""
  "DEFAULT_AUTH0_CONTAINER_PREFIX": "internal-"
  "DEFAULT_AUTH0_SANDBOX_TIMEOUT": 20

Prerequisites

• Node.js >= 6.14.x | download

extensions2

The extensions2 interface provides a mechanism to invoke extensibility points using Webtask platform features that are decoupled from auth0's storage of code.

extensions2.initialize

Initialize the extensions2 interface. A function with the signature function(options) where:

• options - an object having the properties
  • get_db - a function that retrieves an instance of a database connection with the signature function(cb) where:
    • cb - a function with the signature function(error, db).
  • get_env - a function that returns environmental configuration properties with the signature function(property).

extensions2.run_extension

Run an extensibility point. A function with the signature function(options, cb) where:

• options - an object having:
  • tenant - an object representing the tenant on whose behalf the extensibility point is being run.
  • extension_name - a string reprenting the name of the extensibility point
  • payload - an optional object that will be sent as the http request payload to the extensibility point webtask(s). The payload must be in a format that is acceptable to the relevant webtask compiler (see: auth-ext-compilers).
  • client_id - an optional string representing the id of the client for which the extensibility point is being invoked.
  • logger - an optional logger interface that will be used to to log events for the extensibility invocation. If specified, must have a .info property containing a function. -cb - a callback function with the signature function(error, result) where:
  • error - if something went wrong (see Extensions2 Errors for more information).
  • result - an object representing the result where:
    • payload - is the payload returned by the extensibility webtask

Extensions2 Errors

Depending on what went wrong and at what layer of the stack, different types of Errors will be generated according to this hierarchy:

• Error - If the something went wrong before the webtask deployment successfully received the webtask request (mostly communication errors, also timeouts).
• ExtensibilityError - Base class for all errors resulting from the execution of an extensibility point.
  • ExtensibilityPlatformError - Error coming from within the webtask platform that is Auth0 / Webtask's fault and should be flagged.
  • ExtensibilityPointError - Error that resulted from the tenant's action or inaction. Such errors should not be flagged.
    • ExtensibilityImplementationError - Unintentional error caused by the Auth0 tenenat such as:
      • Uncaught sync or async exception thrown in their code
      • Incorrect configuration of the Extensibility Authorization Model.
      • Webtask code that cannot be compiled or that doesn't export an appropriate function
    • ExtensibilityLogicError - The tenant's extensibility webtask correctly ran but whose business logic triggered some sort of error. These errors should be returned more or less as-is to the user-agent making the initial request.

All ExtensibilityErrors will have the following properties:

• message - The error's message which is in human-readable prose.
• statusCode - The http status code determined from the perspective of the user-agent making the original request.
• responseSource - The level of the webtask stack that generated the response. This should be logged by Auth0 services consuming this api to aid in post-mortem debugging.
• code - The .code of the original error (optional).
• errno - The .errno of the original error (optional).
• error - The internal code representing the error for Oauth2 (optional).
• error_description - The full representation of the error for Oauth2 (optional).
• data - Any miscellanous data that the tenant wants to attach to their errors in their extensibility webtask (optional).