在 OAuth 应用授权流程中自定义权限范围-未完纪

你可能已经知道，Dropbox API 授权系统使用权限范围（scopes）来精细控制应用能够使用的功能。应用开发者可以选择应用需要哪些 API 功能，让用户更放心地授权账号访问，也能让用户确信应用只能执行真正需要的操作。

不过，你也许还不知道，可以进一步定制应用在什么时候请求哪些权限范围。下面详细介绍配置与定制方法。

首先要明确：在 App Console 的应用页面中，Permissions 标签页启用的范围，既是应用可以请求的最大集合，也是默认集合。以关联用户账号的应用为例，默认启用 account_info.read，这是此类应用注册时必须启用的范围。在本例中，还会启用 files.content.read 和 files.metadata.read。

应用的权限范围配置（原文截图）。

默认情况下，将用户引导至应用授权页时，会要求他们授权所有这些范围：

https://www.dropbox.com/oauth2/authorize?client_id=<APP_KEY>&response_type=code

默认请求应用已注册范围的授权页（原文截图）。

如果这次不需要全部已启用的范围，可以在构造的 /oauth2/authorize URL 中设置 scope 参数。该参数使用空格分隔的权限范围列表，指定本次只请求其中一个子集。应用不需要全部潜在访问能力时，这种方式很有用，也有助于逐步建立用户信任。

例如，只需要读取用户账号中文件与文件夹的元数据时，可以构造以下 URL：

https://www.dropbox.com/oauth2/authorize?client_id=<APP_KEY>&response_type=code&scope=files.metadata.read

只请求权限子集的授权页（原文截图）。

用户通过该 URL 授权后，应用使用返回的授权码调用 /oauth2/token，将收到类似下面的响应：

{
  "access_token": "<ACCESS_TOKEN>",
  "token_type": "bearer",
  "expires_in": 14400,
  "scope": "files.metadata.read",
  "uid": "<USER_ID>",
  "account_id": "<ACCOUNT_ID>"
}

应用以后需要额外范围时，可以再次请求用户授权：在 scope 参数中列出更多范围，或完全省略这个参数，以请求应用的全部范围。

也可以使用 include_granted_scopes 参数，让新增权限的请求更方便，无需再次明确列出用户已经授予的范围。例如，接下来还需要读取同一用户账号中的文件内容，可以构造另一条 URL：

https://www.dropbox.com/oauth2/authorize?client_id=<APP_KEY>&response_type=code&scope=files.content.read&include_granted_scopes=user

请求额外权限的授权页（原文截图）。

用户通过这个 URL 授权后，应用再用返回的授权码调用 /oauth2/token，将收到类似下面的响应：

{
  "access_token": "<ACCESS_TOKEN>",
  "token_type": "bearer",
  "expires_in": 14400,
  "scope": "files.content.read files.metadata.read",
  "uid": "<USER_ID>",
  "account_id": "<ACCOUNT_ID>"
}

注意，这次访问令牌同时拥有 files.metadata.read 与 files.content.read 权限。

如果应用需要长期无人值守访问，可以在使用上述功能的同时请求 offline 访问，详见Using OAuth 2.0 with offline access。

另外，应用所有者可以更改应用启用的范围，但不会改变某个用户已经授予的范围。例如，用户已授权某组范围后，应用所有者再启用新范围，既有授权不会自动增加该范围；同样，应用所有者禁用某个范围，既有授权也不会自动移除它。

这样，应用不会获得超出用户授权的访问能力，而既有连接也不会因其访问能力被更改而中断。

文章版权归作者所有，未经允许请勿转载。

THE END