Авторизация с помощью Директории¶
Note
Это внутренний документ, так как ссылается на наши интранет-сервисы. Из него можно будет сделать раздел для внешней документации, когда мы будем делать marketplace.
Правильный способ организовать авторизацию в вашем сервисе – использовать Директорию и такое понятие, как Ресурс.
Ресурс, это способ завести в Директории id объекта из вашего сервиса. Когда вы создаёте ресурс, директория узнаёт, о том, что в вашем сервисе есть нечто, у чего есть некий id. Этим id может быть любая строка, уникальная в рамках вашего сервиса. К примеру, ресурсом может быть папка на Диске, очередь в Трекере, проект в Облаке или Лунапарке.
Когда Директория узнала про ваш Ресурс, вы можете связать его с другими объектами Директории – Людьми, Отделами и Командами. Тип связи вы задаёте сами в зависимости от потребностей сервиса. Скажем, Трекер может связать Ресурс своей очереди с конкретным Человеком и указать в названии связи, “admin”. А потом связать этот же Ресурc с Отделом связью с названием “user”.
Когда связи установлены, можно запросить у Директории всё Людей, которые имеют связь с Ресурсом заданного типа. В описанной выше ситуации, можно “спросить” всех Людей, у которых есть связь “user” с определённой Очередью. При этом Директория сама учтёт, что в Отделе могут быть вложенные подотделы, и выдаст вам конечный список людей с учётом всей иерархии. Список их uid этих Людей необходимо закэшировать и использовать для авторизации на своей стороне уже не обращаясь к Директории на каждый запрос.
Итого, поддержка авторизации требует трёх действий¶
Позволить пользователю выбрать кому он даёт доступ:
/suggest/
Связать Ресурс с другими сущностями Директории (создание ресурса и установку связей можно сделать одним действием):
POST /resources/{resource_id}/relations/bulk-update/
;PUT /resources/{resource_id}/relations/
.
Закэшировать у себя список uid, имеющих доступ:
GET /users/?resource={resource_id}&resouce_name=admin&fields=id
.
Остаётся вопрос – как подновлять кэш?¶
Структура компании со временем может изменяться, поэтому должны изменяться и доступы. Поэтому кэш нужно подновлять.
Самое простое решение – установить кэшу ttl. Рекомендуемое значение – 1 час.
Но если вы хотите, чтобы изменения в структуре отражались на авторизации почти мгновенно, то ttl будет недостаточно. В этом случае, нужно будет подписать свой web-hook на событие resource_grant_changed
. В данных, доставляемых в web-hook, есть id вашего ресурса, чей кэш нужно обновить. (Сейчас этот id можно вынуть из payload как payload[‘object’][‘external_id’]
, но это не порядок, в одной из следующих версий API мы будем упрощать структуру событий и формат поменяется).