本文是oauth.com上的教程的翻译。（原文地址）

正如您在阅读完这篇文章后可能已经注意到的那样，OAuth 2.0规范中有很多地方需要做出决策。其中许多事情都没有明确规定，以便允许根据自己的安全要求做出不同的实现。最终结果是大多数OAuth 2.0实现都不可互操作，尽管在实践中，许多实现仍然做出了相同的决策，并且非常相似。

由于实现可以有许多不同的方式，因此为您的服务构建良好的文档至关重要。

本节介绍了您需要记录的内容，以便开发人员能够使用您的API。其中一些项目可以在适当的界面中内联记录（例如开发人员用于客户端注册的界面），有些更适合在API文档的“概述”部分中进行记录。

客户注册

开发人员如何注册新的客户端应用程序以获取客户端ID和可选的秘钥？

• 提供注册页面的链接。
• 您的服务可能会实施动态客户端注册规范，或者拥有用于注册应用程序的专有API
• 您是否为开发人员注册应用程序提供了其他机制？如果是这样，您将需要描述注册应用程序的其他方法。

您的服务应至少询问开发人员他们的应用程序是私密客户端还是公共客户端，并提供注册重定向URI的方法。除此之外，您还应记录您收集的有关应用程序的其他信息，并指出在授权请求期间向最终用户显示哪些信息。

• 应用名称
• 有关应用程序的网页
• 描述
• logo或其他图像
• 有关应用程序使用条款的网页
• 其他信息

endpoint

开发人员将在OAuth流程中使用两个主要endpoint。您的授权endpoint是指导用户开始授权流程的位置。在应用程序获得授权码后，它将在令牌endpoint处交换该代码以获取访问令牌。令牌endpoint还负责为其他授权类型发出访问令牌。

您需要让开发人员知道他们将使用的这两个endpoint的URL。

客户端认证

如果请求中需要客户端身份验证（例如授权码授权），则服务可以通过两种方式接受请求中的客户端ID和秘钥。您的服务可以使用客户端ID作为用户名和秘钥作为密码接受HTTP Basic Auth header中的身份验证，或者接受post body中的字符串作为client_id和client_secret。无论您是要接受这些方法中的一种还是两种，都取决于您的服务，因此您需要告诉开发人员您希望他们如何在请求中包含此身份验证。

此外，您的服务可能支持其他形式的客户端身份验证，例如公钥/私钥对。这在当前部署的OAuth 2.0实现中相对不常见，但是规范保留了开放的可能性。

对发布给应用程序的客户端ID和秘钥的最大或最小长度没有要求，因此通常最好让开发人员知道这些字符串有多大，以便他们可以适当地存储它们。

字符串的大小

由于开发人员在开始编写代码之前不会看到授权码或访问令牌，因此您应该记录他们将遇到的字符串的最大大小。

• 客户端ID
• 客户端秘钥
• 授权码
• 访问令牌

响应类型

您的服务支持哪些响应类型？通常，服务仅支持基于Web和本机应用程序的“code”响应类型。但是，如果您的服务还支持“token”响应类型（在没有中间授权码的情况下发出令牌），那么在文档中指出是很重要的。您应该记录您的服务是否支持其中一个或两个，以及您是否还有其他支持的响应类型。

重定向URL限制

您的服务可能会对开发人员可以使用的已注册重定向URL进行限制。例如，服务通常会禁止开发人员使用非TLS httpendpoint，或限制非生产应用程序使用的endpoint。虽然支持自定义方案对于支持原生应用程序很重要，但某些服务也不允许这些。您应该记录您在注册重定向URL时的任何要求。

默认范围

如果开发人员在授权请求期间未指定范围，则服务可以假定该请求的默认范围。如果是这种情况，您应该记录默认范围。

授权服务器可以忽略开发人员请求的范围，或者添加超出请求范围的其他范围。服务器还可以允许用户根据请求改变范围。这些中的任何一种都是可能的，因此服务应该明确为开发人员指明，以便他们可以考虑访问令牌可能具有不同于他们请求的范围。

该服务还应记录授权码的生命周期，因此开发人员可以了解代码在发布和使用之间的持续时间。授权服务器还可以防止代码被多次使用，并且如果是这样则应该记录该代码。

访问令牌响应

当您发出访问令牌时，访问令牌响应会列出许多可选的参数。您应该记录您的服务支持哪些，以便开发人员知道会发生什么。

响应何时包含expires_in参数？如果令牌会过期，您的服务可能始终包含它，如果没有此参数，您的服务应该可以记录开发人员应该期望的默认过期时间。

响应是否始终包含授予的访问令牌的范围？在响应中返回它通常是一个好主意，但是如果授权范围与请求的范围匹配，许多服务会将其遗漏。无论哪种方式，您都应该记录服务器对此参数的行为方式。

刷新令牌

OAuth 2.0 API开发人员面临的一个更令人困惑或令人沮丧的方面是刷新令牌。重要的是要非常清楚地了解您的服务如何处理刷新令牌（如果有的话）。

如果您的访问令牌过期，您可能希望支持刷新令牌，以便开发人员可以构建继续访问用户帐户的应用程序，而无需用户不断重新授权该应用程序。

您应该清楚地记录哪些受支持的授权类型在响应中应该包含刷新令牌。

当您的服务发出新的访问令牌以响应刷新令牌授权时，您的服务可以同时发出新的刷新令牌，并使之前的刷新令牌到期。这意味着刷新令牌经常刷新，这可能是您的应用程序所需要的。如果是这种情况，请确保开发人员知道这将发生，因此他们不会错误地假设他们获得的第一个刷新令牌将继续无限期地工作。

扩展授权

除了四种基本授权类型（授权码，密码，客户端凭据和隐式）之外，您的服务还可以支持其他授权类型。

某些授权类型标准化为OAuth 2.0的扩展，例如设备流和SAML。某些服务还实现了自己的自定义授权类型，例如将旧版API迁移到OAuth 2.0时。记录您的服务支持的其他授权类型非常重要，并提供有关如何使用它们的文档。