Update Auth0 Applications using the Management API

TL;DR: In this article, we are going to go over Auth0’s Management API v2. We will cover some of its features and how it can help with client management. We will also dive deeper into the process of updating the client name via the Management API. Each Auth0 application has its own unique client ID which allows us to manipulate each client individually. To see a working example, please take a look at this GitHub repo.

Management API v2

When using the Auth0 dashboard, we can see that we can do some of the following items:

1. Create a new client
2. Update the settings for each client
3. Add a new rule for a client
4. And the list goes on and on

Imagine being able to do all of that via the back-end of an application. At Auth0, we have the Management API that can handle client management, hence the name. Anything the Auth0 Dashboard can do, the Management API can do as well, plus more!

If we were to head over to the Auth0 Docs, we could see more information on the Auth0 Management API v2.

"Anything the Auth0 Dashboard can do, the Management API can do as well, plus more!"

Tweet This

How Can I Use It?

When using the Management API, we always need to start with a client. Each client belongs to a project or a website. We’ll start with example.com. We create an Auth0 client via the "Application" tab, hook it up to example.com, and get authentication running for example.com. Great!

One great way we could use it would be to update the client information without having to go into the Auth0 Dashboard every time. We could update the client's name, the description, etc.

The Management API helps with bulk configuration changes and/or automating application changes.

The solution

While the Management API can be used for administrative tasks like updating client information that’s not the only thing it can do. If we were to take a look at this list from Auth0 ManagementClient Documentation, we could see that there is a large list of items that the Management API can handle.

To name a few:

• getUsersByEmail
  • which will get all the users with a particular email address that we input as the first parameter.

auth0.getUsersByEmail(email, function(err, users) {
  console.log(users);
});

• updateRule
  • we can update rules that are currently being used.

var params = { id: RULE_ID };
var data = { name: "my-rule" };
management.updateRule(params, data, function(err, rule) {
  if (err) {
    // Handle error.
  }

  console.log(rule.name); // 'my-rule'.
});

• getClient
  • where we can get the client’s information by using the client id.

management.getClient({ client_id: CLIENT_ID }, function(err, client) {
  if (err) {
    // Handle error.
  }

  console.log(client);
});

"Use Auth0's Management API to take care of administrative tasks."

Tweet This

Real World Example

In this article, we are going to dive deeper into the functionality that updates the client’s name. This can also be done from the dashboard, but we will be using the Management API to do it instead.

The project setup

If there is a current project we would like to add the Management API functionality to, we can add this logic to our back-end code. If we are starting with a new project, be sure to create one. We can start a new project by creating a new repository in GitHub and cloning into that repo. Once in that new project, run the following command to get npm running on it:

npm init

You will be prompted with questions, like the name of the project, etc. If starting from scratch is not what we want to do, again, pull the code from this GitHub repo and follow the instructions in the README.md

Step One - Create the Client and Enable the Management API

First things first, we need to create a client via the Auth0 dashboard. Want to follow along? Now would be the time to sign up for Auth0 for free or sign in to an existing Auth0 account and head to the Auth0 Dashboard.

Note: Remember that each Auth0 application has a unique Client ID.

Now that we are on the Dashboard view, follow these steps:

1. Click on + Create Application
2. Name the App (For example, "management-api-test")
3. Click on Machine to Machine Applications
4. Click on Create
5. Select an API - in our case, we want to select Auth0 Management API
6. Choose scopes. We will choose read:clients and update:clients
7. Click on Authorize.
8. Go to the Settings tab to view Client ID, view the Client Secret, add in Allowed Callback URLs, etc.

There are a few other steps we need to do to make sure our client is ready to communicate with the Management API. If we were to stay in the "Settings" section of our application, scroll down until we see "Token Endpoint Authentication Method". It should say anything but "None", so either "Basic" or "Post". This will allow for the "Client Credentials" to be available.

If we continue scrolling down and click on "Show Advanced Settings", we should see in the menu bar, "Grant Types". Click on that. Once clicked, we should then see that "Client Credentials" has been clicked to show the checkmark.

Do not forget to hit "Save Changes" at the bottom.

With both of those in, we are ready to build the code in our project.

Step Two - Create a File to Handle the ManagementClient

Rather than sticking all of our get and update code into a bunch of little files, let’s create a new file that we’ll use to organize all of our functions.

In the root of the project, create a new file that we will call Auth0Manager.js. This file will have all the Management API logic.

We will need to set up a couple of things before we build this file and start our project. We will need file-system, dotenv, axios, and auth0 installed in our project. We can get these installed by running the following command:

npm install --save file-system dotenv axios auth0

In our Auth0Manager.js file we are going to have the following code:

// Auth0Manager.js

const axios = require("axios");
const ManagementClient = require("auth0").ManagementClient;

/**
 *
 * How this works:
 *  1. Requests an access token using client_id and client_secret
 *  2. Uses the access token to create a new ManagementClient
 *  3. Use the ManagementClient to interact with the API: https://auth0.github.io/node-auth0/module-management.ManagementClient.html
 *
 */

module.exports = (function() {
  let managementClient;

  return {
    init,
    getClient,
    updateClient
  };

  /**
   * Create a management client
   */
  function init() {
    return getToken()
      .then(data => data.access_token)
      .then(token => {
        const managementClient = new ManagementClient({
          domain: `${process.env.CLIENT_DOMAIN}`,
          token,
          audience: `https://${process.env.CLIENT_DOMAIN}/api/v2/`
        });

        // set it so we can use it in our other methods
        this.managementClient = managementClient;
        return true;
      })
      .catch(err => err);
  }

  /**
   * Get an access token from the Auth0 API
   * We will use this access token to connect to the management API
   * To get a token, we need to provide client_id and client_secret
   * Both of these can be found in the APIs section of Auth0 dashboard
   */
  function getToken() {
    // get the info we need
    const clientId = process.env.CLIENT_ID;
    const clientSecret = process.env.CLIENT_SECRET;
    const url = `https://${process.env.CLIENT_DOMAIN}/oauth/token`;

    // make the call to the API via POST
    return axios
      .post(url, {
        client_id: clientId,
        client_secret: clientSecret,
        grant_type: "client_credentials",
        audience: `https://${process.env.CLIENT_DOMAIN}/api/v2/`
      })
      .then(res => res.data)
      .catch(err => err);
  }

  /**
   * Make a call to the Management API to get all the data for a certain client
   * All the things that are available in the dashboard can be accessed here
   * @param string clientId
   */
  function getClient(clientId = null) {
    if (!clientId) clientId = process.env.CLIENT_ID;

    return this.managementClient
      .getClient({ client_id: clientId })
      .then(client => client)
      .catch(err => err);
  }

  /**
   * Take data and update the Auth0Client
   * This can be used to update the entire client via API instead of in the dashboard
   * Very helpful if moving settings from local to a production environment
   *
   * @param {Object} data     The data that will overwrite anything in our dashboard
   * @param {String} clientId The client that we want to update
   */
  function updateClient(data, clientId = null) {
    if (!clientId) clientId = process.env.CLIENT_ID;

    return this.managementClient
      .updateClient({ client_id: clientId }, data)
      .then(client => client)
      .catch(err => err);
  }
})();

As we can see in this file:

1. We have the init() function that is creating the management client.
2. We have the getToken() function that gets an access token for us.
3. The getClient() function grabs the client credentials for us to use.
4. Finally, the updateClient() function allows us to update the client.

.env file

We are going to need a .env file that will hold our client credentials. We need to be sure to create one and put in the following credentials:

CLIENT_DOMAIN="your domain, example: kapehe.auth0.com";
CLIENT_ID="client id from auth0 application";
CLIENT_SECRET="client secret from auth0 application";

Note: Do not forget to add the .env file to .gitignore.

Step Three - Our get-client.js and update-client.js files

Now that we have our Auth0Manager.js and .env files set up, let’s use those functions in two different files, get-client.js and update-client.js.

get-client.js

We will start by building out our get-client.js file. In the root of the project, create a new file named: get-client.js. From there, we are going to want to run the information from the Auth0Manager.js file. That file will look like this:

// get-client.js

require("dotenv").config();
const Auth0Manager = require("./Auth0Manager");
var fs = require("file-system");

Auth0Manager.init()
  .then(() => Auth0Manager.getClient())
  .then(client => {
    var data = fs.writeFileSync("./client-data.json", JSON.stringify(client), {
      encoding: "utf8"
    });
    console.log(data);
    return client;
  })
  .catch(console.error);

Let's go ahead and run this code:

node get-client.js

This will create a new file named client-data.json. The file will be automatically created and appear in the root of the project. In this file, we will see exactly the output of what we are requesting in JSON format. We will see things like:

1. Tenant Name
2. Client Name
3. Client ID

By using the file-system npm package, it was able to "write" a new file, put the client information in a JSON format, and return that client information to the newly created file.

Updating client information

Now that we have that newly created file, client-data.json, we can go into that file and edit things directly from there. We are unable to update client_id but we can, from this file, update the name, description, or even allowed_clients.

In this example, we are going to be updating the name field. Currently, we see the name as management-api-test. Let's go ahead and type in any new name, for example, my-management-api.

Our client-data.json file name field should look like this now:

"name": "my-management-api",

Save that file. Next, we are going to build the file that will read that updated name and send it to the Auth0 Dashboard for us.

update-client.js

Let's build our update-client.js file. In the root of the project, create a new file and name it update-client.js. In that file, we are going to have the following code:

// update-client.js

require("dotenv").config();
const Auth0Manager = require("./Auth0Manager");
var fs = require("file-system");

// the new data we want to set
let newData = fs.readFileSync("./client-data.json", "utf8", function(
  err,
  data
) {
  if (err) {
    throw err;
  }
  return data;
});
newData = JSON.parse(newData);
const updatedData = { name: `${newData.name}` };

Auth0Manager.init()
  .then(() => {
    return Auth0Manager.updateClient(updatedData);
  })
  .then(updatedClient => {
    console.log(updatedClient);
    return updatedClient;
  })
  .catch(err => ({ message: "There was an error!", ...err }));

Once we run the command:

node update-client.js

We will get a returned console of the updatedClient. If we look at the name property in our console, we will see the new name that we inputted earlier! To test that all the way, go to the Auth0 Dashboard and click on "Applications". We now see the updated name for our application.

To update other properties, like the description field, we would need to update the following line in our update-client.js file:

const updatedData = {
  name: `${newData.name}`,
  description: `${newData.description}`
};

And update the description field in the client-data.json file, like so:

"description": "my new description",

We would now be able to see the updated name and description in our console but also in the Auth0 application dashboard view after we run:

node update-client.js

Conclusion

As we saw in this example, the Management API took care of the task of updating the client's name without having to do it via our Auth0 Dashboard. We can use the Management API to do many administrative tasks, so getting familiar with it can be very beneficial in time management but also with ensuring data was updated or transferred correctly.

Go ahead and use the Management API in other available ways. It's amazing what it can do! Again, if you want to see a working example of this project, check out this GitHub repo.