Практическое руководство: управление авторизацией

Обзор

Данное руководство описывает процедуры управления токенами авторизации устройств в Frame.io, включая обновление токенов, отзыв и практики безопасного хранения.

Требования

См. руководство Реализация C2C: настройка, чтобы обеспечить правильную конфигурацию.

Необходимые компоненты:

• Действительный client_secret, выданный Frame.io
• Назначенный вам client_id, как описано в руководстве по аутентификации и авторизации.
• Действительные учетные данные access_token и refresh_token

Понимание токенов авторизации

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

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

Процесс обновления токена доступа

При истечении срока действия токена доступа запросы API получат следующий ответ:

1
{
2
    "code": 401,
3
    "errors": [
4
        {
5
            "code": 401,
6
            "detail": "You are not allowed to access that resource",
7
            "status": 401,
8
            "title": "Not Authorized"
9
        }
10
    ],
11
    "message": "Not Authorized"
12
}

Выполните следующую команду для получения нового токена:

$
curl -X POST https://api.frame.io/v2/auth/token \
>
    --header 'x-client-version: 2.0.0' \
>
    --form 'client_id=[client_id]' \
>
    --form 'client_secret=[client_secret]' \
>
    --form 'grant_type=refresh_token' \
>
    --form 'refresh_token=[refresh_token]' \
>
    | python -m json.tool

Данная реализация требует множественных факторов аутентификации для повышения безопасности. Неавторизованной стороне потребуется получить как refresh_token, так и client_secret для имитации вашей интеграции.

Обновление создает следующий ответ:

1
{
2
    "access_token": "[access_token]",
3
    "expires_in": 28800,
4
    "refresh_token": "[refresh_token]",
5
    "token_type": "bearer"
6
}

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

Попытка повторного использования токена обновления с истекшим сроком действия приводит к следующему:

1
{
2
    "error": "invalid_request"
3
}

Это указывает на то, что токен уже был обработан ранее и больше не действителен.

Обработка неудачных ответов обновления

Так как значения refresh_token одноразовые, при сбое получения ответа обновления из-за прерывания сети или отключения системы потребуется повторно запустить полную последовательность аутентификации/авторизации.

Этот протокол безопасности, хотя и может причинять неудобства, необходим для поддержания целостности системы.

Процесс отзыва токенов

Может потребоваться прекращение доступа к Frame.io, например завершение проекта или сброс приложения. Реализуйте правильные процедуры отзыва при прекращении текущей авторизации.

Выполните следующую команду для отзыва авторизации:

$
curl -X POST https://api.frame.io/v2/auth/revoke \
>
    --include \
>
    --header 'x-client-version: 2.0.0' \
>
    --form 'client_id=[client_id]' \
>
    --form 'client_secret=[client_secret]' \
>
    --form 'token=[refresh_token]'

Система возвращает заголовки без полезной нагрузки. Успешное выполнение обозначается кодом состояния 200:

HTTP/2 200
...

После отзыва операции Frame.io, требующие аутентификации с помощью access_token, будут возвращать Несанкционированный доступ. Восстановление доступа требует повторного сопряжения устройства с проектом.

Реализация хранения токенов

Для поддержания сохраняемой авторизации при перезапуске системы требуется безопасное хранение токенов. Следуйте этим основным рекомендациям:

Внедрите элементы управления доступом пользователей: ограничьте видимость токенов и доступ к ним исключительно процессами приложения. Включите шифрование хранилища: реализуйте шифрование для сохраненных токенов, включая client_secret и учетные данные авторизации. Никогда не храните ключи авторизации в формате простого текста. Обеспечьте разделение учетных данных: хотя наше демонстрационное приложение Python объединяет хранилище, производственные среды должны разделять токены авторизации и client_secret. Учитывайте эти факторы:

• client_secret и client_id представляют постоянные учетные данные устройства — их потеря приводит к полному отказу устройства.
• Токены авторизации регулярно обновляются в процессе работы устройства
• Раздельное хранилище гарантирует, что повреждение токенов потребует только повторного сопряжения устройства, а не полного сброса аутентификации.

Хотя SQLite обеспечивает оптимальные возможности хранения токенов, как минимум реализуйте раздельное хранилище для данных авторизации и основных учетных данных.

Дальнейшие шаги

Мы рады вашему прогрессу и предлагаем перейти к руководству по состоянию подключения и heartbeats. Если у вас возникли вопросы, свяжитесь с нами по адресу.