TL;DR: В тази статия ще разгледаме API v2 за управление на Auth0. Ще разгледаме някои от неговите функции и как може да помогне при управлението на клиенти. Също така ще се потопим по-дълбоко в процеса на актуализиране на името на клиента чрез API за управление. Всяко приложение Auth0 има свой собствен уникален клиентски идентификатор, който ни позволява да манипулираме всеки клиент поотделно. За да видите работещ пример, моля, погледнете това репо на GitHub.

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

Когато използваме таблото за управление Auth0, можем да видим, че можем да направим някои от следните елементи:

  1. Създайте нов клиент
  2. Актуализирайте настройките за всеки клиент
  3. Добавете ново правило за клиент
  4. И списъкът продължава и продължава

Представете си, че можете да правите всичко това чрез задния край на приложение. В Auth0 имаме API за управление, който може да управлява управлението на клиента, откъдето идва и името. Всичко, което таблото за управление на Auth0 може да направи, API за управление също може да направи, плюс още!

Разгледайте Блога на Auth0 🔐 и намерете всичко, което трябва да знаете за инфраструктурата за самоличност, управление на достъпа, SSO, JWT удостоверяване и най-новото в сигурността. 👉 AUTH0 БЛОГ 👈

Ако се насочим към Auth0 Docs, бихме могли да видим повече информация за Auth0 Management API v2.

Как мога да го използвам?

Когато използваме API за управление, винаги трябва да започнем с клиент. Всеки клиент принадлежи към проект или уебсайт. Ще започнем с example.com. Създаваме клиент Auth0 чрез раздела „Приложение“, свързваме го към example.com и стартираме удостоверяване за example.com. Страхотен!

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

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

Решението

Въпреки че API за управление може да се използва за административни задачи като актуализиране на клиентска информация, това не е единственото нещо, което може да направи. Ако трябваше да разгледаме този списък от Auth0 ManagementClient Documentation, бихме могли да видим, че има голям списък от елементи, които 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); });

Пример от реалния свят

В тази статия ще се потопим по-дълбоко във функционалността, която актуализира името на клиента. Това може да се направи и от таблото за управление, но вместо това ще използваме API за управление, за да го направим.

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

Ако има текущ проект, към който бихме искали да добавим функционалността на API за управление, можем да добавим тази логика към нашия бек-енд код. Ако започваме с нов проект, не забравяйте да създадете такъв. Можем да започнем нов проект, като създадем ново хранилище в GitHub и клонираме в това репо. След като влезете в този нов проект, изпълнете следната команда, за да стартирате npm в него:

Ще бъдете подканени с въпроси, като името на проекта и т.н. Ако започването от нулата не е това, което искаме да направим, отново изтеглете кода от това репо на GitHub и следвайте инструкциите в README.md

Първа стъпка — Създайте клиента и активирайте API за управление

Първо, трябва да създадем клиент чрез таблото за управление Auth0. Искате ли да следвате? Сега е моментът да се регистрирате за Auth0 безплатно или да влезете в съществуващ акаунт в Auth0 и да се насочите към Таблото за управление на Auth0.

Забележка: Не забравяйте, че всяко приложение Auth0 има уникален клиентски идентификатор.

Сега, когато сме в изгледа на таблото, изпълнете следните стъпки:

  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 и т.н.

Има няколко други стъпки, които трябва да направим, за да сме сигурни, че клиентът ни е готов да комуникира с API за управление. Ако трябваше да останем в секцията „Настройки“ на нашето приложение, превъртете надолу, докато видите „Метод за удостоверяване на крайна точка на токен“. Трябва да пише всичко друго освен „Няма“, така че или „Основно“ или „Публикуване“. Това ще позволи „Клиентските идентификационни данни“ да бъдат налични.

Ако продължим да превъртаме надолу и щракнете върху „Показване на разширени настройки“, трябва да видим в лентата с менюта „Типове безвъзмездни средства“. Кликнете върху това. След като щракнем, трябва да видим, че е щракнато върху „Клиентски идентификационни данни“, за да се покаже отметката.

Не забравяйте да натиснете „Запазване на промените“ в долната част.

С тези и двете сме готови да изградим кода в нашия проект.

Стъпка втора — Създайте файл за обработка на ManagementClient

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

В корена на проекта създайте нов файл, който ще наречем Auth0Manager.js. Този файл ще съдържа цялата логика на 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.

get-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 вместо нас.

update-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

Заключение

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

Продължете и използвайте API за управление по други налични начини. Удивително е какво може да направи! Отново, ако искате да видите работещ пример за този проект, вижте това репо на GitHub.

Относно Auth0

Auth0, световен лидер в Identity-as-a-Service (IDaaS), предоставя на хиляди клиенти във всеки пазарен сектор единственото решение за идентичност, от което се нуждаят за своите уеб, мобилни, IoT и вътрешни приложения. Нейната разширяема платформа безпроблемно удостоверява и защитава повече от 2,5 милиарда влизания на месец, което я прави обичана от разработчиците и надеждна от глобалните предприятия. Централата на компанията в САЩ в Белвю, Вашингтон, и допълнителните офиси в Буенос Айрес, Лондон, Токио и Сидни поддържат нейните глобални клиенти, които се намират в над 70 държави.

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

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