Creating and Installing a Custom Extension

Rather than using one of Auth0's provided extensions, you may choose to create your own.

Creating a Custom Extension

To begin creating your custom extension, please feel free to fork/clone any one of Auth0's extension repositories:

Alternatively, you may follow the Development Instructions provided via the New Extension window that appears when you click on the + CREATE EXTENSION button. To view the Development Instructions, navigate to the Extensions page of the Management Portal. Click on the + CREATE EXTENSION button. On the popup displayed click on the Check out this command line tool link. The Development Instructions popup is displayed. These instructions allow you to create your own extension using the command line.

Extensions can also be installed using wt-cli. The command would look like the following:

wt create {file} --name {extensionName} --param owner=“{tenant}” --param version="1.0.0"

Once the extension is installed you can make updates using the following:

wt update {extensionName} {file} -p {tenant}

Learn more about wt-cli by visiting the documentation and the github repository.

Installing a Custom Extension

Once you have created your own extension, you may install it manually via the Extensions page of the Auth0 Management Portal.

Near the top right-hand side of the window, click the + CREATE EXTENSION button.

In the New Extension window that pops open, provide the GitHub URL to the repository that contains the files required by your extension.

At this time, only repositories hosted by GitHub may be used.

Alternatively, you may host your files elsewhere and simply provide a link to the webtask.json file in the box (e.g. http://example.com/webtask.json).

Once you have provided the link to your files and clicked Continue, you will be prompted to install the extension. If you would like to proceed, click Install.

Under the Installed Extensions tab you will find your newly-installed extension listed.

Extension Lifecycle

Let's have a look at what happens behind the scenes when installing and uninstalling custom extensions.

When the user clicks on Install, a Client and a ClientGrant are created for the extension with the scopes defined on the webtask.json. Also, access is granted to Management APIv2 Resource Server.

For this webtask.json:

{
  "name": "my-extension";
  "auth0": {
    "createClient": true,
    "scopes": "create:rules"
  }
}

The following Client and a ClientGrant would be created:

Clients.create({
  name: 'my-extension'
}).then(function (client) {
  return Grants.create({
    audience:  'https://jcenturion.auth0.com/api/v2/',
    client_id: client.client_id,
    scope: "create:rules"
  }).then(function () {
    return addSecrets(wt, client, wtUrl);
  });
});

NOTE: If you are creating a Cron, then you can omit the "createClient": true from the webtask.json file. A Client is always created by default for Cron extensions.

The installation dialog will warn the user that the extension will have access to certain scopes. In this case: create:rules.

The webtask will be created with the AUTH0_CLIENT_ID and AUTH0_CLIENT_SECRET information set as secrets.

After the webtask is created, /.extensions/on-install (POST /onInstallUrl) is called sending a JWT for validating that Auth0-manage is the one calling it.

The expected success status is 204. Keep in mind that if the hooks fail, then the install (or uninstall) will fail as well.

Install and uninstall URLs are configurable through webtask.json.

{
  "name": "my-extension";
  "auth0": {
    "scopes": "create:rules",
    "onInstallUrl": "/my-own-on-install" 
  }
}

onInstallPath and onUninstallPath are mandatory if you want auth0-dashboard to call them.

In order to edit an extension /.extensions/on-update (PUT /onUpdateUrl) is called, with a JWT for validating that Auth0-manage is the one calling it. Once the validation is successful the webtask and the client associated to the webtask are updated with the changes. Again, the expected success status is 204.

When the user clicks on Uninstall, /.extensions/on-uninstall (DELETE /onUninstallUrl) is called, with a JWT for validating that Auth0-manage is the one calling it. Afterwards, the webtask and the client associated to the webtask are removed.

The JWT, used for authenticating the calls to the hooks for both /.extensions/on-install and /.extensions/on-uninstall, looks like the following:

{
  aud: {extensionUrl + hookPath},      
  iss: {auth0Domain},                 
  iat: timespan
}

The extension should validate the JWT. See this for the validation applied.