Oauth 2.0 概述

在 OAuth 2.0 中，用户可以安全的方式授权第三方应用程序使用与该特定用户相关的 Zoho Mail 资源。 

第 1 步：用户想要使用第三方应用程序/集成以访问或自动运行 Zoho Mail。 

第 2 步：第三方应用连接至 Zoho Mail 并使用此 API 代表用户请求令牌。

第 3 步：Zoho Mail 为第三方应用提供临时令牌和密钥代码。此密钥代码用于阻止任何伪造事件及（对于服务器）识别发出请求的应用程序。 

第 4 步：此应用会将用户重定向至 Zoho Mail 并给出临时令牌和密钥代码。在 Zoho Mail 中，用户会见到一个提示，此提示指示授权第三方应用访问其帐户和数据。 

第 5 步：该用户向第三方应用授权。此时，第三方应用提供临时令牌及密钥代码，并使用此 API 获取永久访问令牌。 

第 6 步：用户通过此应用进行的所有未来操作将通过访问令牌和密钥代码完成。 

第三方应用 - 获取客户端 ID 和客户端密钥：

您需要向 Zoho Developer 控制台注册此应用以获取客户端 ID 和客户端密钥。  要注册您的应用程序，请遵循以下指示信息： 

1. 导航至 Zoho Developer 控制台。
2. 在“API 凭证”页面中，点击添加客户端 ID 以创建新的客户端 ID 和客户端密钥。 
   
3. 输入客户端名称、客户端域和授权重定向 URI。（重定向 URI 是应用的回调入口点，不同于应用的入口点。）
   
4. 您将获取一组 OAuth 2.0 详细信息，以及仅在 Zoho 与该应用程序之间共享的客户端 ID 和客户端密钥。
   ​

获取授权

接下来，您必须调用授权 URI - https://accounts.zoho.com/oauth/v2/auth 

https://accounts.zoho.com/oauth/v2/auth?scope={scope}&client_id={client_id}&response_type=code&access_type={offline or online}&redirect_uri={redirect_uri}

授权 URI 应包含以下参数作为查询字符串：

参数	类型	描述
*client_id	唯一标识	注册应用时分配给该应用的 ID。
*response_type	字符串	"code"
*redirect_uri	URI	注册期间使用的回调 URI。
*scope	字符串	指定您的应用所允许的作用域。必须用逗号分隔。 语法： Servicename.scopename.Operation 示例：VirtualOffice.folders.READ, VirtualOffice.folders.CREATE
access_type	字符串	offline/online（默认值：online）。 "online" access_type 仅给予您的应用程序有效期为 1 小时的访问令牌。 "offline" access_type 将给予您的应用程序访问令牌和刷新令牌。
prompt	字符串	prompt=consent. 每次您的应用尝试访问用户凭证时，提示用户同意。
state	字符串	一个生成值，此值使回调与其关联授权请求相关。

*必需参数

作用域名称和操作

API 名称	作用域名称	操作
Accounts	accounts	READ 和 UPDATE
Organization	partner.organization
Organization Subscriptions	organization.subscriptions
Organization Spam	organization.spam	READ
Organization Account Management	organization.accounts	READ、CREATE 和 UPDATE
Messages	messages	CREATE、READ、UPDATE 和 DELETE
Attachments	attachments
Groups	organization.groups
Labels	tags
Folders	folders
Domains	organization.domains

调用此授权 URI 后，系统将对用户显示“用户同意页面”。

如果用户点击接受，那么 Zoho 会将用户重定向回您的网站并提供“授权代码”。您的应用程序现在可使用授权代码请求 Zoho 提供访问令牌。如果用户点击拒绝，那么服务器会返回错误。

提示再次同意

您可在每次用户登录时提示用户向您的应用重新授权（通过向身份验证请求添加 prompt=consent 参数）。添加 prompt=consent 后，用户登录您的应用时，系统将显示同意屏幕。因此，仅应在必要时才添加 prompt=consent。 

注：获取刷新令牌时，prompt=consent 参数是必需的。

获取访问令牌

您的应用程序收到授权代码时，可发出接收访问令牌（您的应用将使用此令牌接收用户凭证）的新请求。因为这是整个过程中的重要步骤，所以设置这些参数时也应特别谨慎。 

参数	类型	描述
*code	字符串	从初始请求获取的授权代码。
*client_id	唯一标识	注册应用时分配给该应用的 ID。
*client_secret	字符串	您的应用的密钥。在您注册应用时分配，可在您的配置文件中获取。
*redirect_uri	URI	您的回调 URI，在注册应用程序期间给出。
*scope	字符串	指定您的应用所允许的作用域。必须用逗号分隔。
*state	字符串	在整个授权过程中必须保持不变。
grant_type	字符串	"authorization_code"

*必需参数

回复

发送请求及授权代码后，Zoho 会向您的应用发出回复，此回复将给出以下信息。

• expires_in - 令牌的余下有效期（以毫秒计）。
• token_type - 令牌类型。("bearer")
• access_token - 用户的访问令牌。此令牌可用于最终 API 调用，并且仅在 1 小时内有效。
• refresh_token - 访问令牌超时后要使用的刷新令牌。此令牌是永久令牌，可多次使用以刷新应用并获取新的访问令牌。

可存储此数据，因此用户每次访问您的应用时不必进行授权。

使用访问令牌

调用 Zoho Mail REST API 时，以头的形式发送访问令牌。

带有可用作用域的访问令牌调用 URI 时，系统会对应用程序提供该作用域内允许的令牌。因此，您可获取用户凭证并实现常规注册流程。

获取和使用刷新令牌

在您的访问请求中，您可请求返回刷新令牌及访问令牌。刷新令牌允许 REST API 即使在用户未登录的情况下也可访问您的应用程序。要请求刷新令牌。请向身份验证请求添加 access_type=offline。

刷新令牌始终由 prompt=consent 生成。刷新令牌的最大数目为 20。达到此限制后，所生成的第一个刷新令牌将被删除。

访问令牌的有效期受到限制。在大多数情况下，访问令牌将在 1 小时内到期。在此之前，访问令牌的使用不受限制。到期后，您的应用必须使用刷新令牌来请求新的访问令牌。

对于此新请求，要包含的参数为：

参数	类型	描述
client_id	唯一标识	注册应用时分配给该应用的 ID。
client_secret	字符串	您的应用的密钥。 在您注册应用时分配，可在您的配置文件中获取。
grant_type	字符串	refresh_token
redirect_uri	URI	您的回调 URI。
refresh_token	字符串	所提供的刷新令牌及访问令牌。

您现在将收到新的访问令牌，您可使用它继续获取用户凭证。此访问令牌的时间限制也是 1 小时。

某些 API 要求执行管理员身份验证，某些 API 仅在进行用户身份验证后执行。一些特定 API 既可由管理员也可由用户执行。但是，请求 URL 会根据角色而变化。