TL;DR: в этой статье мы рассмотрим API управления Auth0 v2. Мы расскажем о некоторых его функциях и о том, как он может помочь в управлении клиентами. Мы также углубимся в процесс обновления имени клиента через Management API. Каждое приложение Auth0 имеет свой уникальный идентификатор клиента, который позволяет нам управлять каждым клиентом индивидуально. Чтобы увидеть рабочий пример, взгляните на этот репозиторий GitHub.

API управления v2

При использовании панели управления Auth0 мы видим, что можем выполнять некоторые из следующих действий:

  1. Создать нового клиента
  2. Обновите настройки для каждого клиента
  3. Добавить новое правило для клиента
  4. И этот список можно продолжать и продолжать

Представьте, что все это можно сделать через серверную часть приложения. В Auth0 у нас есть Management API, который может управлять клиентом, отсюда и название. Все, что может сделать панель инструментов Auth0, может сделать и Management API, а также многое другое!

Посетите Блог Auth0 🔐 и найдите все, что вам нужно знать об инфраструктуре идентификации, управлении доступом, системе единого входа, аутентификации JWT и последних новостях в области безопасности. 👉 AUTH0 БЛОГ 👈

Если бы мы перешли к документации Auth0, мы могли бы увидеть больше информации об API управления Auth0 v2.

Как я могу его использовать?

При использовании Management API нам всегда нужно начинать с клиента. Каждый клиент принадлежит проекту или сайту. Начнем с example.com. Мы создаем клиент Auth0 через вкладку «Приложение», подключаем его к example.com и запускаем аутентификацию для example.com. Здорово!

Один отличный способ, который мы могли бы использовать, — обновить информацию о клиенте без необходимости каждый раз заходить на панель инструментов Auth0. Мы могли бы обновить имя клиента, описание и т. д.

Management API помогает вносить массовые изменения конфигурации и/или автоматизировать изменения приложений.

Решение

Хотя Management API можно использовать для административных задач, таких как обновление информации о клиенте, это не единственное, что он может делать. Если бы мы взглянули на этот список из документации Auth0 ManagementClient, мы бы увидели большой список элементов, с которыми может работать Management API.

Назвать несколько:

auth0.getUsersByEmail(email, function (err, users) { console.log(users); });
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'. });
management.getClient({ client_id: CLIENT_ID }, function (err, client) { if (err) { // Handle error. } console.log(client); });

Пример реального мира

В этой статье мы углубимся в функциональность, которая обновляет имя клиента. Это также можно сделать с панели инструментов, но вместо этого мы будем использовать Management API.

Настройка проекта

Если есть текущий проект, в который мы хотели бы добавить функциональность Management API, мы можем добавить эту логику в наш внутренний код. Если мы начинаем новый проект, обязательно создайте его. Мы можем начать новый проект, создав новый репозиторий в GitHub и клонировав его в этот репозиторий. Оказавшись в этом новом проекте, запустите следующую команду, чтобы запустить на нем npm:

Вам будут предложены вопросы, например, название проекта и т. д. Если начинать с нуля — это не то, что мы хотим сделать, опять же, вытащите код из этого репозитория GitHub и следуйте инструкциям в README.md

Шаг первый — создайте клиент и включите Management API

Прежде всего, нам нужно создать клиента через панель управления Auth0. Хотите следовать вместе? Сейчас самое время зарегистрироваться на Auth0 бесплатно или войти в существующую учетную запись Auth0 и перейти к Панель управления Auth0.

Примечание. Помните, что каждое приложение Auth0 имеет уникальный идентификатор клиента.

Теперь, когда мы находимся в представлении Dashboard, выполните следующие действия:

  1. Нажмите на + Create Application
  2. Назовите приложение (например, «management-api-test»)
  3. Нажмите на Machine to Machine Applications
  4. Нажмите на Create
  5. Выберите API — в нашем случае мы хотим выбрать Auth0 Management API
  6. Выберите области. Мы выберем read:clients и update:clients
  7. Нажмите на Authorize.
  8. Перейдите на вкладку Settings, чтобы просмотреть Client ID, просмотреть Client Secret, добавить Allowed Callback URLs и т. д.

Нам нужно выполнить еще несколько шагов, чтобы убедиться, что наш клиент готов к обмену данными с Management API. Если бы мы остались в разделе «Настройки» нашего приложения, прокрутите вниз, пока не увидите «Метод аутентификации конечной точки токена». Там должно быть что угодно, кроме «Нет», поэтому либо «Основной», либо «Пост». Это позволит сделать «Учетные данные клиента» доступными.

Если мы продолжим прокручивать вниз и нажмем «Показать дополнительные настройки», мы должны увидеть в строке меню «Типы грантов». Нажмите на это. После нажатия мы должны увидеть, что «Учетные данные клиента» были нажаты, чтобы показать галочку.

Не забудьте внизу нажать «Сохранить изменения».

С обоими из них мы готовы создать код в нашем проекте.

Шаг второй — создайте файл для управления ManagementClient

Вместо того, чтобы вставлять весь наш код get и update в кучу маленьких файлов, давайте создадим новый файл, который мы будем использовать для организации всех наших функций.

В корне проекта создайте новый файл, который назовем Auth0Manager.js. В этом файле будет вся логика Management API.

Нам нужно будет настроить пару вещей, прежде чем мы создадим этот файл и начнем наш проект. Нам понадобятся file-system, dotenv, axios и auth0, установленные в нашем проекте. Мы можем установить их, выполнив следующую команду:

npm install --save file-system dotenv axios auth0

В нашем файле Auth0Manager.js у нас будет следующий код:

// 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); } })();

Как мы видим в этом файле:

  1. У нас есть функция init(), которая создает клиента управления.
  2. У нас есть функция getToken(), которая получает для нас токен доступа.
  3. Функция getClient() получает учетные данные клиента для использования.
  4. Наконец, функция updateClient() позволяет нам обновить клиент.

.env-файл

Нам понадобится файл .env, в котором будут храниться учетные данные нашего клиента. Нам нужно обязательно создать его и ввести следующие учетные данные:

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

Примечание. Не забудьте добавить файл .env в .gitignore.

Шаг третий — наши файлы get-client.js и update-client.js

Теперь, когда у нас настроены файлы Auth0Manager.js и .env, давайте воспользуемся этими функциями в двух разных файлах, get-client.js и update-client.js.

получить-client.js

Мы начнем с создания нашего файла get-client.js. В корне проекта создайте новый файл с именем: get-client.js. Оттуда мы собираемся запустить информацию из файла Auth0Manager.js. Этот файл будет выглядеть так:

// 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);

Давайте продолжим и запустим этот код:

node get-client.js

Это создаст новый файл с именем client-data.json. Файл будет создан автоматически и появится в корне проекта. В этом файле мы увидим именно то, что мы запрашиваем, в формате JSON. Мы увидим такие вещи, как:

Используя пакет file-system npm, он смог «записать» новый файл, поместить информацию о клиенте в формате JSON и вернуть эту информацию о клиенте во вновь созданный файл.

Обновление информации о клиенте

Теперь, когда у нас есть только что созданный файл client-data.json, мы можем перейти в этот файл и редактировать прямо оттуда. Мы не можем обновить client_id, но можем из этого файла обновить name, description или даже allowed_clients.

В этом примере мы будем обновлять поле name. В настоящее время мы видим имя как management-api-test. Давайте продолжим и введем любое новое имя, например, my-management-api.

Теперь наше поле client-data.json файла name должно выглядеть так:

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

Сохраните этот файл. Далее мы собираемся создать файл, который будет считывать это обновленное имя и отправлять его на панель инструментов Auth0 для нас.

обновление-client.js

Давайте создадим наш файл update-client.js. В корне проекта создайте новый файл и назовите его update-client.js. В этом файле у нас будет следующий код:

// 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 }));

Как только мы запустим команду:

node update-client.js

Мы получим возвращенную консоль updatedClient. Если мы посмотрим на свойство name в нашей консоли, мы увидим новое имя, которое мы ввели ранее! Чтобы проверить это полностью, перейдите на панель инструментов Auth0 и нажмите «Приложения». Теперь мы видим обновленное имя нашего приложения.

Чтобы обновить другие свойства, такие как поле description, нам нужно обновить следующую строку в нашем файле update-client.js:

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

И обновите поле description в файле client-data.json следующим образом:

"description": "my new description",

Теперь мы сможем увидеть обновленные name и description в нашей консоли, а также в представлении панели инструментов приложения Auth0 после запуска:

node update-client.js

Вывод

Как мы видели в этом примере, Management API позаботился о задаче обновления имени клиента без необходимости делать это через нашу панель управления Auth0. Мы можем использовать Management API для выполнения многих административных задач, поэтому знакомство с ним может быть очень полезным для управления временем, а также для обеспечения правильного обновления или передачи данных.

Идите вперед и используйте API управления другими доступными способами. Удивительно, что он может сделать! Опять же, если вы хотите увидеть рабочий пример этого проекта, посмотрите этот репозиторий GitHub.

О Auth0

Auth0, мировой лидер в области «Идентификация как услуга» (IDaaS), предоставляет тысячам клиентов в каждом секторе рынка единственное решение для идентификации, которое им нужно для их веб-приложений, мобильных приложений, IoT и внутренних приложений. Его расширяемая платформа беспрепятственно аутентифицирует и защищает более 2,5 миллиардов входов в месяц, что делает ее любимой разработчиками и надежной компанией со всего мира. Штаб-квартира компании в США в Белвью, штат Вашингтон, и дополнительные офисы в Буэнос-Айресе, Лондоне, Токио и Сиднее обслуживают своих клиентов по всему миру, которые находятся в более чем 70 странах.

Для получения дополнительной информации посетите https://auth0.com или подпишитесь на @auth0 в Twitter.

Первоначально опубликовано на https://auth0.com.