Аутентификация | Frame.io API Documentation

API-интерфейс Frame.io V4 использует службу Adobe Identity Management Service (IMS) — платформу идентификации Adobe на базе протокола OAuth 2.0. Существует две категории аутентификации.

Межсерверная аутентификация

Позволяет техническим или сервисным учетным записям выполнять действия без участия пользователя. Доступна только для учетных записей Frame.io V4, управляемых через Adobe Admin Console.

Аутентификация пользователя

Выполняет действия от имени пользователя, которому принадлежит токен. Доступна для всех учетных записей Frame.io V4, управляемых через Adobe Admin Console, а также для учетных записей под управлением Frame, которые перешли на аутентификацию Adobe.

Руководства по аутентификации в SDK

SDK Frame.io управляют полным жизненным циклом OAuth, включая URL-адреса авторизации, обмен токенами, их автоматическое обновление и отзыв. Выберите язык программирования, чтобы начать работу.

SDK для Python

Процессы аутентификации ServerToServerAuth, WebAppAuth и SPAAuth с поддержкой синхронного и асинхронного режимов.

SDK для TypeScript

Процессы аутентификации ServerToServerAuth, WebAppAuth, SPAAuth и NativeApp для Node.js и браузерных сред.

Если вы создаете серверную службу или автоматизацию, начните с межсерверной аутентификации. Если в вашем приложении пользователи проходят авторизацию, выберите процесс веб-приложения (если можете хранить секретный ключ клиента) или одностраничного приложения (если не можете).

Аутентификация пользователя

Учетные данные для аутентификации пользователя создаются в Adobe Developer Console. Adobe поддерживает три типа учетных данных — выберите тот, который соответствует архитектуре вашего приложения.

Веб-приложение OAuth

Подходит для серверных приложений, которые могут обеспечить безопасное хранение секретного ключа клиента (Flask, Django, FastAPI, Express и других).

Одностраничное приложение OAuth

Подходит для браузерных приложений, интерфейсов CLI или приложений для ПК, которые не могут обеспечить безопасное хранение секретного ключа клиента. Использует PKCE.

Встроенное приложение OAuth

Подходит для встроенных приложений для мобильных устройств или ПК, которые используют перенаправление через пользовательские схемы URI.

В состав SDK Frame.io для Python не входит класс учетных данных для встроенных приложений, поскольку в Python нет стандартного способа регистрации обработчиков пользовательских схем URI. Вместо этого используйте веб-приложение с локальным сервером обратного вызова. При этом SDK для TypeScript поддерживает все три типа учетных данных.

Межсерверная аутентификация

Межсерверная аутентификация позволяет вашему приложению действовать от имени пользователя сервисной учетной записи без участия человека. Приложение проходит аутентификацию с помощью учетных данных клиента и напрямую получает токен доступа. Действия сервисной учетной записи отображаются в Frame.io под ее собственным именем. Права доступа сервисной учетной записи управляются через Adobe Admin Console и Developer Console. В настоящее время имя сервисной учетной записи изменить нельзя. Подробнее о реализации — в руководствах по конкретным SDK выше.

Подробнее о настройке сервисных учетных записей — в разделе Автоматизация настройки с помощью межсерверной поддержки Frame.io.

Как работает аутентификация Adobe IMS

Adobe Identity Management Service (IMS) — это функция управления идентификацией Adobe на базе протокола OAuth 2.0, которая поддерживает аутентификацию. Для создания токена доступа необходимо выполнить два шага.

Авторизация пользователя

Сначала пользователь авторизует приложение перед созданием токена. Подробнее — здесь.

Обмен токенами

Затем получите токен доступа. Предыдущий шаг возвращает в теле ответа код, который необходим на данном этапе. Точные конечные точки для доступа и используемые параметры — здесь.

Описанные выше шаги обязательны для всех трех типов учетных данных приложений. Однако существуют различия в способах обращения к конечным точкам IMS /authorize/v2 и /token/v3 для получения токена. После того как вы получите токен доступа, вы сможете использовать его для взаимодействия с API-интерфейсом Frame.io V4.

При межсерверной аутентификации этап авторизации пользователя отсутствует — приложение напрямую использует учетные данные клиента для получения токена доступа через тип разрешения client_credentials.

Использование токена доступа

После получения токена доступа включайте его в заголовок Authorization каждого запроса к API-интерфейсу.

Authorization: Bearer <ACCESS_TOKEN>

SDK Frame.io делает это за вас — просто передайте сам токен (или вызываемый объект, возвращающий токен) при создании клиента.

Срок жизни токена

Токены доступа являются краткосрочными: обычно срок их действия истекает через 1 час. Для процессов аутентификации пользователя (веб-приложение, одностраничное приложение, встроенное приложение) служба Adobe IMS также возвращает токен обновления, который можно использовать для получения нового токена доступа без повторного входа пользователя в систему. Токены обновления имеют более длительный срок жизни, но со временем тоже истекают.

При межсерверной аутентификации токены обновления не используются. Сами учетные данные клиента никогда не истекают (если только они не были обновлены вручную), поэтому приложение всегда может запросить новый токен доступа.

SDK Frame.io автоматически управляют обновлением токенов. Подробнее — в руководствах по конкретным SDK.

Области доступа

При создании учетных данных в Adobe Developer Console вам потребуется настроить области доступа OAuth, которые определяют, к чему получит доступ ваше приложение. SDK Frame.io по умолчанию используют следующие области доступа.

Процесс	Области доступа по умолчанию
Межсерверная аутентификация	`openid AdobeID frame.s2s.all`
Аутентификация пользователя (веб-приложение, одностраничное приложение, встроенное приложение)	`openid email profile offline_access additional_info.roles`

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

Устаревшие токены разработчика

Для учетных записей, переведенных на версию V4, которые еще не управляются через Adobe Admin Console, можно продолжать использовать устаревшие токены разработчика, управление которыми осуществляется на сайте Frame.io Developer. Передавайте такие токены напрямую в SDK.

1 from frameio import Frameio
2 
3 client = Frameio(
4     token="YOUR_LEGACY_DEVELOPER_TOKEN",
5     headers={"x-frameio-legacy-token-auth": "true"},
6 )

При использовании устаревшего токена разработчика с API-интерфейсом V4 необходимо добавлять заголовок x-frameio-legacy-token-auth со значением true во все запросы к API-интерфейсу. Если вы используете SDK, устанавливайте его через параметры запроса клиента.

Устаревшие токены разработчика не истекают, но они являются переходным механизмом. Для новых интеграций и производственных нагрузок мы рекомендуем использовать один из приведенных ниже процессов OAuth 2.0. Подробнее — в руководстве по миграции.

Если вы являетесь пользователем Enterprise и переходите с устаревшей версии Frame.io на V4, обратитесь к своему менеджеру по работе с клиентами за помощью в настройке устаревшего токена разработчика и версии V4.

Подробнее о переходе с устаревших токенов на аутентификацию Adobe IMS — в руководстве по миграции.