Устарел

Практическое руководство: авторизация (оборудование)

Введение

В этом руководстве мы расскажем, как выполнять аутентификацию и авторизацию оборудования «С камеры в облако» (C2C) в проекте Frame.io. Мы рассмотрим как традиционный метод сопряжения с вводом кода вручную, так и новый метод сопряжения с QR-кодом для улучшенного пользовательского интерфейса.

Что потребуется?

Если вы еще не читали руководство Перед внедрением, просмотрите его перед тем, как продолжить!Также вы должны были получить от нашей команды client_secret, который будет использоваться для идентификации вашей интеграции. Если вы не получили client_secret, ознакомьтесь с этим введением в экосистему C2C и свяжитесь с нашей командой.

Предварительные требования для сопряжения по QR-коду

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

  • Активация флага функции: в вашей учетной записи Frame.io должен быть включен специальный флаг функции (v4.c2c_qr_code_activate). Этот флаг функции позволит получить доступ к методу сопряжения на основе QR-кода. Назначенный представитель Frame.io может помочь включить эту функцию для выбранной учетной записи.
  • Совместимость камер: убедитесь, что аппаратное обеспечение вашей камеры обновлено для поддержки создания QR-кода во время процесса сопряжения устройства.

Пошаговое руководство по потоку аппаратной авторизации

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

  • Статья справки о том, как добавить новые устройства.
  • Обучающее видео о том, как авторизовать Teradek Cube.

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

  • Перенаправление в веб-браузер.
  • Обработка входа/аутентификации пользователей Frame.io.
  • Перечисление/выбор учетной записи и проекта для подключения.
  • Обрабатывает любые элементы пользовательского интерфейса, выходящие за рамки простого отображения информации.

Улучшение пользовательского интерфейса с помощью сопряжения QR-кодов

По мере роста требований к эффективности и простоте использования пользователи все больше ожидают удобного взаимодействия со своими устройствами. Текущий процесс сопряжения камер с сервисом C2C от Frame.io требует выполнения нескольких шагов, включая ввод кода сопряжения вручную. Хотя этот процесс функционален, его можно оптимизировать.

Используя QR-коды — аналогично процессу сопряжения устройств в стриминговых сервисах, таких как Netflix или Disney+ — мы можем упростить процесс, исключить ошибки ввода вручную и сократить время сопряжения камеры.

Идентификация устройства (client_id)

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

В случае с устройствами мы называем это client_id устройства, в зависимости от выбранного вами шаблона авторизации. При настройке реализации вам следует подумать о том, как вы будете это делать. Вы можете использовать серийный номер устройства, UUID или какую-либо уникальную идентифицирующую строку. Будьте осторожны, чтобы не раскрыть личную идентификационную информацию. Адрес электронной почты пользователя, например не является допустимым значением для использования в качестве client_id.

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

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

Шаг 1. Запрос кода устройства

Начнем реализацию. Первое, что нам нужно сделать, — это запросить код устройства для предоставления пользователю устройства. Мы делаем это, вызывая конечную точку /v2/auth/device/code:

Традиционный метод сопряжения

curl -X POST https://api.frame.io/v2/auth/device/code \
    --form 'client_id=[client_id]' \
    --form 'client_secret=[client_secret]' \
    --form 'scope=asset_create offline' \
    | python -m json.tool

Включение сопряжения через QR-код

Для включения сопряжения на основе QR-кода требуется незначительное изменение в вызове API. В запрос кода устройства необходимо добавить два новых заголовка. Это позволяет устройствам напрямую ссылаться на страницу сопряжения и упрощает процесс сопряжения.

curl -X POST https://api.frame.io/v2/auth/device/code \
    --header "x-client-version: 2.0.0" \
    --header "x-client-platypus-enabled: true" \  # New header to enable QR code
    --form 'client_id=[client_id]' \
    --form 'client_secret=[client_secret]' \
    --form 'scope=asset_create offline' \
    | python -m json.tool

Примечание. Здесь мы используем данные формы, а не данные JSON. Конечные точки аутентификации C2C принимают только данные формы. После аутентификации другие конечные точки будут принимать полезные нагрузки JSON, но конечные точки аутентификации вернут ошибку, если будут отправлены полезные нагрузки JSON.

Параметры полезной нагрузки

  • client_id: уникальный идентификатор физического устройства. Это значение должно гарантированно быть уникальным для устройства. Это может быть серийный номер или случайно созданный UUID.
  • client_secret: это значение будет выдано вам службой поддержки Frame.io и идентифицирует вашу модель устройства. Это значение не должно быть доступно пользователю и должно быть зашифровано в состоянии покоя.
  • scope: разрешения, которые мы запрашиваем, с пробелами в качестве разделителей. Устройства могут запрашивать только следующие две области доступа:
  • asset_create: позволяет устройству создавать и добавлять ресурсы.
  • офлайн: позволяет устройству обновлять свою собственную авторизацию с помощью токена обновления. Срок действия токенов авторизации истекает через 8 часов, поэтому без этой области доступа пользователю потребуется повторно авторизовывать свое устройство каждые 8 часов.

На практике для устройств почти всегда запрашивают обе области доступа.

Понимание ответа API-интерфейса

При создании запроса мы получаем ответ, похожий на этот:

Ответ традиционного сопряжения

{
  "device_code": "[device_code]",
  "expires_in": 120,
  "interval": 5,
  "name": "MyDevice-[client_id]",
  "user_code": "573131"
}

Ответ сопряжения QR-кода

{
  "device_code": "[device_code]",
  "expires_in": 120,
  "interval": 5,
  "name": "MyDevice-[client_id]",
  "user_code": "573131",
  "verification_uri": "https://next.frame.io/pair",
  "verification_uri_complete": "https://next.frame.io/pair/573131"
}

Разбор ответа

  • device_code: код устройства должен быть скрыт от пользователя. Он используется для идентификации этого запроса авторизации при опросе, чтобы увидеть, успешно ли пользователь ввел код.
  • expires_in: количество секунд до истечения срока действия этого кода.
  • interval: как долго пользователь должен ждать между запросами опроса, чтобы увидеть, ввел ли пользователь код.
  • имя: имя устройства, которое мы пытаемся подключить.
  • user_code: шестизначный код, который пользователь вводит в Frame.io для сопряжения устройства с проектом.
  • verification_uri: это URL-адрес, который пользователи вводят вручную в случае, если QR-код не будет отсканирован. Он должен быть лаконичным и легко запоминаться.
  • verification_uri_complete: этот URL-адрес содержит код сопряжения и предназначен для нетекстовой передачи (например, QR-код). При сканировании он автоматически направит пользователя к интерфейсу сопряжения, чтобы выбрать учетную запись и проект для подключения устройства.

Отображение QR-кода для пользователя

Теперь, когда у нас есть verification_uri_complete, мы можем создать QR-код на основе этого URL-адреса и отобразить его пользователю на экране устройства. Это позволяет пользователю просто отсканировать QR-код с мобильного устройства или камеры, что оптимизирует процесс сопряжения.

Пример: экран камеры с показанным QR-кодом

Вставить изображение или иллюстрацию экрана камеры с отображаемым QR-кодом.

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

Шаг 2. Опрос для авторизации пользователя

После того как мы передали код сопряжения или отобразили QR-код пользователю, нам нужно проверить, ввел ли он его. Для этого можно выполнить следующий запрос:

curl -X POST https://api.frame.io/v2/auth/token \
    --form 'client_id=[client_id]' \
    --form 'device_code=[device_code]' \
    --form 'grant_type=urn:ietf:params:oauth:grant-type:device_code' \
    | python -m json.tool

Параметры полезной нагрузки

  • client_id: идентификатор client_id, отправленный в шаге 1.
  • device_code: код device_code, который вернул /v2/auth/device/code.
  • grant_type: тип разрешения авторизации, которое выдает наша система OAuth. Это значение всегда будет urn:ietf:params:oauth:grant-type:device_code.

Первые несколько раз, когда мы делаем этот запрос, мы, вероятно, получим такой ответ:

{
  "error": "authorization_pending"
}

Но не стоит беспокоиться! Это не критическая ошибка. Это просто означает, что пользователь еще не ввел пользовательский код в пользовательский интерфейс Frame.io. Все, что нам нужно делать, это продолжать опрос, пока это не будет сделано.

Если этого не произойдет, отобразится такая ошибка:

{
  "error": "expired_token"
}

Это означает, что срок действия кода истек до того, как пользователь смог его ввести. В таком случае нам следует создать новый код сопряжения или QR-код, выполняя действия в шаге 1, показать его пользователю, а затем возобновить опрос.

В итоге мы должны получить такой ответ:

{
  "access_token": "[access_token]",
  "expires_in": 28800,
  "refresh_token": "[refresh_token]",
  "token_type": "bearer"
}

Если полезная нагрузка вашего ответа выглядит именно так «Поздравляем!», вы авторизовали ваше первое устройство «С камеры в облако». Все идет отлично!

Рассмотрим эту полезную нагрузку ответа, чтобы убедиться, что мы ее понимаем:

  • access_token: это ваш ключ к остальной части сервера Frame.io. Нам нужно будет добавить его в заголовок остальных запросов, которые мы будем делать в этих руководствах.
  • expires_in: количество секунд до истечения срока действия access_token. После истечения времени токена его потребуется обновить, что мы выполним в следующем руководстве.
  • refresh_token: токен, который мы можем использовать для управления нашим access_token. Чаще всего он будет использоваться для обновления нашей авторизации, но также может быть использован для ее отзыва.
  • token_type: всегда будет bearer для API-интерфейса C2C и он не требует действий.

Объединяем шаги

Теперь, когда мы знаем, какие вызовы нам нужно сделать, объедините их в псевдокод, похожий на Python. Помните, что наш код устройства может истечь, поэтому нам нужно учесть эту возможность при настройке логики:

Python
1def authorize_with_frame():
2    """
3    Handles authorizing our device with Frame.io.
4    """
5
6    # Our client ID can be a serial number, UUID, or some other unique string.
7    client_id = THIS_DEVICE.get_serial_number()
8
9    while True:
10        # Make the call to Frame.io to get our device codes.
11        pairing_codes = c2c.get_device_codes(client_id)
12
13        # We need to keep track of how long we have been polling for
14        polling_started = datetime.now()
15
16        # Now we are going to poll for authorization until the user enters the code.
17        while True:
18
19            # Re-write this output each time we poll. Note: This message will only update once
20            # per `interval` (e.g., 5 seconds), so if a smooth countdown is desired, that will
21            # need a different implementation.
22            print(
23                f"\rPAIRING CODE: {pairing_codes.user_code}, "
24                f"EXPIRES IN: {pairing_codes.expires_in - (datetime.now() - polling_started).seconds} seconds"
25            )
26
27            # Wait for `interval` before polling each time.
28            sleep(pairing_codes.interval)
29
30            # Make a call to Frame.io to see if the user has entered the code and authorized
31            # the device.
32            authorization, error = c2c.poll_for_authorization(
33                client_id, pairing_codes.device_code
34            )
35
36            if error and error.message == "authorization_pending":
37                # If the authorization is pending, try again.
38                continue
39            elif error and error.message == "expired_token":
40                # If the pairing codes have expired, break to generate new codes.
41                break
42            elif error:
43                # If we get another error, we should raise it. (advanced error handling will
44                # be covered in another tutorial)
45                raise Exception(error.message)
46
47            return authorization

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

Поиск и устранение неисправностей

Если вы оказались здесь, что-то пошло не так! Интеграции с третьей стороной без ошибок почти не бывает В этом разделе приведен набор распространенных проблем и описаны действия, которые наиболее вероятно их решат. Просмотрите следующий список и выясните, похоже ли что-то на проблему, с которой вы столкнулись.

Если здесь нет подходящего решения, сообщите нам и мы добавим ее сюда.

  • Я не вижу кнопку «Connect Device»: если вы переходите в панель управления C2C и не видите кнопку «Connect Device», то происходит одно из двух:
  • C2C не включен для вашей учетной записи: если экран пустой и отображается сообщение о том, что C2C недоступен для вашей учетной записи, менеджер учетной записи должен включить его для вашего проекта в настройках учетной записи.
  • Вы не являетесь менеджером устройств: если экран пустой и отображается сообщение об отсутствии разрешений, менеджер учетной записи должен либо изменить разрешения для пользователей, имеющих право подключать устройства C2C, либо добавить вас в роль с такими разрешениями.
  • У вас уже подключено устройство: после подключения первого устройства большая синяя кнопка «Add New Device» исчезает, и вместо этого нужно перейти в меню из трех точек в правом верхнем углу панели подключений C2C.
  • Ошибка недопустимого клиента: invalid_client возвращается, когда предоставляемая вами информация об устройстве не соответствует ничему из наших записей. Скорее всего, это означает, что ваш client_secret неверен.
  • Ошибка неверного запроса: bad_request возвращается, когда данные запроса имеют неправильный формат. Удостоверьтесь, что вы не сделали ошибку в написании название поля или не забыли добавить обязательное поле.

Далее

Если вы еще этого не сделали, рекомендуем связаться с нашей командой, а затем перейти к следующему руководству: LINK. Надеемся на скорую обратную связь!

Список отложенных вопросов

Список задач

Добавить план действий для партнеров, которые не могут создать динамический QR-код,

то есть заставить их отображать «Перейдите по **verification_uri**, чтобы ввести этот код» в качестве резервного плана