用户通常需要注册API密钥或学习其他方法来验证请求,然后才能使用您的API发出请求。API验证用户身份的方式各不相同。有些API要求您在请求标头中包含API密钥,而其他API则需要精心设计的安全性,因为它们需要保护敏感数据,证明身份并确保对请求的篡改。在本部分中,您将了解有关身份验证和授权的更多信息,以及在文档中应重点关注的内容。
目录
- 定义术语
- API缺乏安全性的后果
- 不同类型的授权
- API密钥基本认证HMAC(基于哈希的消息授权码)OAuth 2.0
- 文档化授权
- 授权部分示例
- 活动:授权分析
定义术语
首先,让我们定义一些关键术语:
- 身份验证:指证明正确的身份
- 授权:指允许某个动作
API可能会对您进行身份验证,但未授权您发出特定请求。
API缺乏安全性的后果
为什么API甚至需要身份验证?对于只读API,有时用户不需要密钥。但是大多数商业API确实需要以API密钥或其他方法的形式进行授权。如果您的API没有任何安全性,则用户无需进行任何注册即可无限次数地调用API。允许无限制的请求将使您的API的收入模型变得困难。
此外,如果没有身份验证,就没有一种将请求与特定用户数据相关联的简便方法。而且,还没有一种方法可以防止恶意用户的请求删除恶意用户的请求(例如,通过对另一个帐户进行DELETE请求)。
最后,您无法跟踪谁在使用您的API或最常使用哪些端点。显然,API开发人员必须考虑验证和授权对其API的请求的方法。总体而言,使用API进行身份验证和授权具有以下目的:
- 仅向注册用户验证对API的调用
- 跟踪谁在发出请求
- 跟踪API的使用
- 阻止或限制超出速率限制的任何请求者
- 将不同的权限级别应用于不同的用户
不同类型的授权有几种授权方法。
以下是您可能会遇到的各种API授权:
- API keys
- Basic Auth
- HMAC
- OAuth
API Key
大多数API都要求您注册一个API密钥才能使用该API。API密钥是一个长字符串,通常包含在请求URL或请求标头中。API密钥主要用作识别进行API调用的人员的方式(验证您使用该API的身份)。API密钥也可能与您注册的特定应用程序相关联。
API可能会同时为您提供公钥和私钥。公钥通常包含在请求中,而私钥则更像是密码,仅在服务器到服务器的通信中使用。对于某些API文档网站,当您登录该网站时,您的API密钥会自动填充到示例代码和API资源管理器中。
Basic Auth
另一种授权类型称为基本身份验证。使用此方法,发送方将username:password放入请求标头中。用户名和密码使用Base64编码,Base64是一种编码技术,可将用户名和密码转换为一组64个字符,以确保安全传输。这是请求标头中的基本身份验证的示例:
Authorization: Basic bG9sOnNlY3VyZQ==
使用基本身份验证的API也将使用HTTPS,这意味着消息内容将在HTTP传输协议内进行加密。(没有HTTPS,人们可以很容易地解码用户名和密码。)
当API服务器收到消息时,它将解密消息并检查标头。在对字符串进行解码并分析了用户名和密码之后,它将决定是接受还是拒绝请求。
在Postman中,可以通过以下方式配置基本授权:单击“授权”选项卡,从下拉选择器中选择“基本验证”,然后在冒号右侧的每一行上键入用户名和密码。标头选项卡将显示一个键值对,如下所示:
Authorization: Basic RnJlZDpteXBhc3N3b3Jk
当您输入用户名和密码并选择基本身份验证时,Postman会自动为您处理Base64编码。
HMAC(基于哈希的消息授权码)
HMAC代表基于哈希的消息授权代码,是一种更强大的身份验证类型,在金融API中更为常见。使用HMAC,发送者和接收者都知道一个别人没有的秘密密钥。发件人基于某些系统属性(例如,请求时间戳和帐户ID)创建一条消息。
然后,该消息由secret密钥编码,并通过安全哈希算法(SHA)传递。(哈希是基于算法的字符串加扰。)结果值(称为签名)被放置在请求标头中。
当接收方(API服务器)接收到请求时,它将采用相同的系统属性(请求时间戳和帐户ID),并使用密钥(只有请求者和API服务器才知道)和SHA生成相同的字符串。如果字符串与请求标头中的签名匹配,则它接受请求。如果字符串不匹配,则请求被拒绝。
这是描述此工作流程的图:
重要的是,私有密钥(对于重建哈希至关重要)仅对发送者和接收者而言是已知的。密钥不包含在请求中。当您要确保请求既真实又未被篡改时,可以使用HMAC安全性。
OAuth 2.0
OAuth 2.0是一种用于验证和授权用户的流行方法。此方法依赖于身份验证服务器与API服务器进行通信以授予访问权限。使用网站时,您通常会看到OAuth 2.0,并被提示使用Twitter,Google或Facebook之类的服务登录。
OAuth有几种变体,即“one-legged OAuth”和“three legged OAuth”。如果您没有敏感数据需要保护,则使用one-legged OAuth。如果您只是在获取常规的只读信息,则可能是这种情况。相反,当您需要保护敏感数据时,使用thress-legger OAuth。在这种情况下,有三个组进行交互:
- 认证服务器
- 资源服务器(API服务器)
- 用户或应用
这是OAuth 2.0的基本工作流程:
首先,消费者应用程序将应用程序密钥和机密发送到身份验证服务器上的登录页面。如果通过了身份验证,则身份验证服务器将使用访问令牌响应用户。
将该访问令牌打包到对请求的响应重定向(302)中的查询参数中。重定向将用户的请求指向资源服务器(API服务器)。
然后,用户向资源服务器(API服务器)发出请求。将访问令牌添加到API请求的标头中,其单词为Bearer,后跟令牌字符串。API服务器会检查用户请求中的访问令牌,并决定是否对用户进行身份验证。
访问令牌不仅为请求者提供身份验证,而且还定义了用户如何使用API的权限。此外,访问令牌通常会在一段时间后过期,并要求用户再次登录。有关OAuth 2.0的更多信息,请参阅以下资源:
- Learn API Technical Writing 2: REST for Writers (Udemy), by Peter Gruenbaum
- OAuth simplified, by Aaron Parecki
文档化认证
在API文档中,您无需向外部用户详细说明身份验证的工作原理。实际上,不解释身份验证过程的内部细节可能是最佳实践,因为这会使黑客更难滥用API。
但是,您确实需要解释一些必要的信息,例如:
- 如何获取API密钥
- 如何验证请求
- 与无效身份验证有关的错误消息
- 身份验证信息的敏感性
- 令牌到期时间
如果您有公共密钥和私有密钥,则应解释每个密钥的使用位置,并注意不要共享私有密钥。如果不同的许可证层为API调用提供了不同的访问权限,则这些许可证层应在您的授权部分或其他地方明确显示。
由于在开发人员开始使用API之前,API密钥部分通常是必不可少的,因此该部分需要出现在帮助的开头。
授权部分示例
以下是API文档中授权部分的一些示例。
SendGrid
SendGrid提供API密钥的详细说明,从基础知识开始,解释“什么是API密钥?”。在上下文中,API密钥主题与其他帐户管理主题一起出现。
使用Twitter,因为涉及到OAuth 2.0授权要求,所以需要提供并提供详细的示例。
Amazon Web Services
Amazon示例使用HMAC。该过程非常复杂,因此其中包含完整的图表以显示用户需要执行的步骤。
Dropbox
像Twitter一样,Dropbox也使用OAuth 2.0。他们的文档不仅包括一个图,还包括两个图以及对该过程的扩展说明。
授权活动
使用您确定的开源项目,标识有关对API请求的授权的信息。回答以下问题:
- 向API发出请求需要哪种授权?
- 授权中是否有不同的访问级别(例如,免费与专业级)来确定您可以发出多少个请求或可以访问的信息类型?
- 您是否可以获取API密钥或对API进行测试调用所需的任何授权方法?
- 如何将有关授权的信息整合到入门教程中?