操作指南：管理授权

概述

本指南概述了在 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 提供最佳的令牌存储功能，但至少应为授权数据和核心凭据实施分离存储。

后续步骤

我们很高兴看到您的进展，并邀请您继续阅读连接状态和心跳指南。 如有任何问题或疑虑，请联系我们的团队。