方法：承認の管理

概要

このガイドでは、トークンの更新、失効、安全な保管の慣行など、Frame.io におけるデバイス承認トークン管理の概要について説明します。

前提条件

C2C の実装：セットアップガイドを参照して、適切な構成を確認してください。

重要な必須コンポーネント：

• Frame.io によって発行された有効な client_secret
• 割り当てられた client_id （詳細は認証および承認ガイドを参照）
• 有効な access_token および refresh_token 資格情報

承認トークンの概要

デバイス認証に関する前のガイドでは、ユーザー認証を通じて初期承認トークンを取得するプロセスについて説明しました。

アクセストークンは、その機能を約 8 時間維持します。デバイスを頻繁に再ペアリングする必要性を排除するため、承認とともに更新トークンを取得するための offline スコープが実装されています。この更新トークンを使用すると、有効期限が切れた際に新しいアクセストークンを生成できます。

更新トークンは 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
...

失効後、access_token 認証を必要とする Frame.io 操作は Not Authorized を返します。アクセスを復元するには、デバイスをプロジェクトに再ペアリングする必要があります。

トークンストレージの実装

システムの再起動後も永続的な承認を維持するには、安全なトークンストレージが必要です。以下の重要なガイドラインを遵守してください。

**ユーザーアクセス制御の実装：**トークンの可視性とアクセスをアプリケーションプロセスのみに制限します。

ストレージ暗号化の有効化：client_secret や承認資格情報を含めて、保存されるトークンの暗号化を実装します。承認鍵は絶対にプレーンテキスト形式では維持しないでください。

**資格情報分離の維持：**当社のデモ用 Python アプリケーションはストレージを統合しますが、本番環境では承認トークンを client_secret と分離する必要があります。次の要因を考慮してください。

• client_secret と client_id は永続的なデバイス資格情報であり、紛失は永続的なデバイス障害につながる
• 承認トークンは、デバイス操作全体を通じて定期的に更新される
• ストレージが分離されているので、トークンストレージが破損しても、必要となるのはデバイスの再ペアリングだけであり、認証の完全なリセットは不要

SQLite は最適なトークンストレージ機能を提供していますが、少なくとも承認データと基本的な資格情報用にはストレージを個別に実装してください。

次のステップ

次は、接続ステータスおよびハートビートガイドに進んでください。不明点や懸念がありましたら、当社チームまでお問い合わせください。