OAUTH



文本预览：

OAuth 开发文档

1 OAuth 介绍

OAUTH 协议为用户资源的授权提供了一个安全的,开放而又简易的标准.与以往的授权方式不同之处是 OAUTH 的授权不会使第三方触及到用户的帐号信 息(如用户名与密码) ,即第三方无需使用用户的用户名 与密码就可以申请获得该用户资源的授权,因此 OAUTH 是安全的.同时,任何第三方都可以使用 OAUTH 认证服务, 任何服务提供商都可以实现自身的 OAUTH 认证服务, 因而 OAUTH 是开放的. 业界提供了 OAUTH 的多种实现如 PHP,JavaScript,Java,Ruby 等各种语言开发包,大大节约了程序员的时间,因而 OAUTH 是简易的. 目前互联网很多服务如 Open API, 很多大头公司如 Google, Yahoo, Microsoft 等都提供了 OAUTH 认证服务,这些都足以说明 OAUTH 标准逐渐成为开放资源授权 的标准. 在官方网站的首页,可以看到下面这段简介: authorization An open protocol to allow secure API authorization in a simple and standard method from desktop and web applications. 大概意思是说 OAUTH 是一种开放的协议,为桌面程序或者基于 BS 的 web 应用提供了一种简单的,标准 的方式去访问需要用户授权的 API 服务. OAUTH 类似于 Flickr Auth, Google's AuthSub, Yahoo's BBAuth, Facebook Auth 等.OAUTH 认证授权具有以下特点: 1. 简单:不管是 OAUTH 服务提供者还是应用开发者,都很容易于理解与使用; 2. 安全:没有涉及到用户密钥等信息,更安全更灵活; 3. 开放:任何服务提供商都可以实现 OAUTH,任何软件开发商都可以使用 OAUTH;

2 OAUTH 产生的背景

典型案例: 如果一个用户拥有两项服务: 一项服务是图片在线存储服务 A, 另一个是图片在线打印服务 B. 如下图所示.由于服务 A 与服务 B 是由两家不同的服务提供商提供的,所以用户在这两家服务提供商的网 站上各自注册了两个用户, 假设这两个用户名各不相同,密码也各不相同.当用户要使用服务 B 打印存储 在服务 A 上的图片时,用户该如何处理?法一:用户可能先将待打印的图片从服务 A 上 下载下来并上传到 服务 B 上打印,这种方式安全但处理比较繁琐,效率低下;法二:用户将在服务 A 上注册的用户名与密码 提供给服务 B,服务 B 使用用户的帐号再 去服务 A 处下载待打印的图片,这种方式效率是提高了,但是安 全性大大降低了,服务 B 可以使用用户的用户名与密码去服务 A 上查看甚至篡改用户的资源.

很多公司和个人都尝试解决这类问题,包括 Google,Yahoo,Microsoft,这也促使 OAUTH 项目组的产 生.OAuth 是由 Blaine Cook,Chris Messina,Larry Halff 及 David Recordon 共同发起的,目的在于为 API 访问授权提供一个开放的标准.OAuth 规范的 1.0 版于 2007 年 12 月 4 日发布.通过官方网址: http://oauth.net 可以阅读更多的相关信息.

3 OAUTH 相关术语

在弄清楚 O

AUTH 流程之前,我们先了解下 OAUTH 的一些术语的定义:

URL: OAUTH 相关的三个 URL:

o o o

Request Token URL: 获取未授权的 Request Token 服务地址; User Authorization URL: 获取用户授权的 Request Token 服务地址; Access Token URL: 用授权的 Request Token 换取 Access Token 的服务地址;

相关的参数定义: OAUTH 相关的参数定义:

o

oauth_consumer_key: 使用者的 ID, OAUTH 服务的直接使用者是开发者开发出来的应用. 所以该参数值的获取一般是要去 OAUTH 服务提供商处注册一个应用,再获取该应用的 oauth_consumer_key.如 Yahoo 该值的注册地址为: https://developer.yahoo.com/dashboard/ oauth_consumer_secret:oauth_consumer_key 对应的密钥. oauth_token oAuth 进行到最后一步得到的一个"黄金招牌".有了这个"黄金招牌"求资源的网站 B 就 求资源的网站 可以大摇大摆去 拥有资源的网站 A 抓取任意有权限可以被抓取的资源了. oauth_token_secret 上面那个东西的私钥

o o

o

oauth_signature_method: 请求串的签名方法,应用每次向 OAUTH 三个服务地址发送请 求时,必须对请求进行签名.签名的方法有:HMAC-SHA1,RSA-SHA1 与 PLAINTEXT 等三 种. oauth_signature: 用上面的签名方法对请求的签名. oauth_timestamp: 发起请求的时间戳,其值是距 1970 00:00:00 GMT 的秒数,必须是大 于 0 的整数.本次请求的时间戳必须大于或者等于上次的时间戳. oauth_nonce: 随机生成的字符串,用于防止请求的重放,防止外界的非法攻击. oauth_version: OAUTH 的版本号,可选,其值必须为 1.0.

o o o o

响应代码: OAUTH HTTP 响应代码:

HTTP 400 Bad Request 请求错误

o o o o o o o o

Unsupported parameter 参数错误 Unsupported signature method 签名方法错误 Missing required parameter 参数丢失 Duplicated OAuth Protocol Parameter 参数重复 Invalid Consumer Key 非法 key Invalid / expired Token 失效或者非法的 token Invalid signature 签名非法 Invalid / used nonce 非法的 nonce

HTTP 401 Unauthorized 未授权

4 OAUTH 认证授权流程

在弄清楚了 OAUTH 的术语后,我们可以对 OAUTH 认证授权的流程进行初步认识.其实,简单的来说,OAUTH 认证授权就三个步骤,三句话可以概括:

4.1

获取未授权的 request token

4.1.1

请求参数

oauth_consumer_key: 消费方键值. oauth_signature_method: 消费方签署本请求所用的签名方法. oauth_signature: 签名,定义于签署请求 (签署请求). oauth_timestamp: 定义于 Nonce and Timestamp (单次值与时间戳). oauth_nonce: 定义于 Nonce and Timestamp (单次值与时间戳).

oauth_version: 可选.如果存在,其值必须为 1.0.如果参数不存在,服务提供方必须假定协 议版本为 1.0. 服务提供方对 1.0 以外取值的响应尚未定义. 额外参数: 由服务提供方定义的任意额外参数

4.1.2

服务方返回结果

响应包含如下参数: oauth_token: 请求

令牌 oauth_token_secret: 令牌密钥 附加参数: 由服务提供方定义的任意参数.

4.2

获取用户授权的 Request Token

4.2.1

请求参数

oauth_token: 可选.在前述步骤中获得的请求令牌.服务提供方可以声明此参数为必须,也可以允许不 包含在授权 URL 中并提示用户手工输入. oauth_callback: 可选.消费方可以指定一个 URL,当 获取用户授权 (获取用户授权)成功后,服务提供方 将重定向用户到这个 URL. 附加参数: 由服务提供方定义的任意参数.

4.2.2

服务提供方将用户引导回消费方

如果消费方在 oauth_callback 中提供了回调 URL(在消费方引导用户至服务提供方 (消费方引导 用户至服务提供方)中描述),则服务提供方构造一个 HTTP GET 请求 URL,重定向用户浏览器到该 URL,并包含如下参数: oauth_token: 被用户授权或否决的请求令牌 回调 URL 可以包含消费方提供的查询参数, 服务提供方必须保持已有查询不变并追加 oauth_token 参数.

4.3

用授权的 Request Token 换取 Access Token

4.3.1

消费方请求访问令牌参数 消费方请求访问令牌参数

oauth_consumer_key: 消费方键值. oauth_token: 之前获取的请求令牌. oauth_signature_method: 消费方使用的签署方法. oauth_signature: 签署请求 (签署请求)中定义的签名. oauth_timestamp: 在单次值与时间戳 (单次值与时间戳)中定义. oauth_nonce: 在单次值与时间戳 (单次值与时间戳)中定义. oauth_version: 可选. 如果存在, 其值必须为 1.0. 如果参数不存在, 服务提供方必须假定协议版本为 1.0. 服务提供方对 1.0 以外取值的响应尚未定义.

4.3.2

返回参数

oauth_token: 访问令牌. oauth_token_secret: 令牌密钥.

4.4

访问受保护资源

4.4.1

请求参数

oauth_consumer_key: 消费方键值. oauth_token: 访问令牌. oauth_signature_method: 消费方使用的签署方法. oauth_signature: 签署请求 (签署请求)中定义的签名. oauth_timestamp:

定义于单次值与时间戳 (单次值与时间戳). 单次值与时间戳 oauth_nonce: 定义于单次值与时间戳 (单次值与时间戳). 单次值与时间戳 oauth_version: 如果存在, 如果存在 其值必须为 1.0. 如果参数不存在, 服务提供方必须假定协议版本为 1.0. 可选. 服务提供方对 1.0 以外取值的响应尚未定义. 附加参数: 服务提供方指定的附加参数. 服务提供方指定的附加参数

4.4.2

具体流程

当应用拿到 Access Token 后 后,就可以有权访问用户授权的资源了.大家肯能看出来了 大家肯能看出来了,这三个步骤不 就是对应 OAUTH 的三个 URL 服务地址嘛 服务地址嘛.一点没错,上面的三个步骤 中,每个步骤分别请求一个 URL,并 每个步骤分别请求一个 且收到相关信息,并且拿到上步的相关信息去请求接下来的 URL 直到拿到 Access Token 并且拿到上步的相关信息去请求接下

来的 Token.具体的步骤如下 图所示:

具体每步执行信息如下: A. 使用者(第三方软件)向 OAUTH 服务提供商请求未授权的 Request Token.向 Request Token URL 发起 请求,请求需要带上的参数见上图 请求需要带上的参数见上图. B. OAUTH 服务提供商同意使用者的请求 服务提供商同意使用者的请求,并向其颁发未经用户授权的 oauth_token 与对应的 oauth_token_secret,并返回给使用者 并返回给使用者.

C. 使用者向 OAUTH 服务提供商请求用户授权的 Request Token.向 User Authorization URL 发起请求, 请求带上上步拿到的未授权的 token 与其密钥. D. OAUTH 服务提供商将引导用户授权.该过程可能会提示用户,你想将哪些受保护的资源授权给该应用. 此步可能会返回授权的 Request Token 也可能不返回.如 Yahoo OAUTH 就不会返回任何信息给使用者. E. Request Token 授权后,使用者将向 Access Token URL 发起请求,将上步授权的 Request Token 换取 成 Access Token.请求的参数见上图,这个比第一步 A 多了一个参数就是 Request Token. F. OAUTH 服务提供商同意使用者的请求,并向其颁发 Access Token 与对应的密钥,并返回给使用者. G. 使用者以后就可以使用上步返回的 Access Token 访问用户授权的资源. 从上面的步骤可以看出,用户始终没有将其用户名与密码等信息提供给使用者(第三方软件),从而 更安全.用 OAUTH 实现背景一节中的典型案例:当服务 B(打印服务)要访问用户的服务 A(图片服务) 时,通过 OAUTH 机制,服务 B 向服务 A 请求未经用户授权的 Request Token 后,服务 A 将引导用户在服务 A 的网站上登录,并询问用户是否将图片服务授权给服务 B.用户同意后,服务 B 就可以访问用户在服务 A 上的图片服务. 整个过程服务 B 没有触及到用户在服务 A 的帐号信息. 如下图所示, 图中的字母对应 OAUTH 流程中的字母:

5 关于签名说明

在第一步获取 Request Token 时,需要使用 Consumer Key 和 API Key Secret 进行签名 的 Consumer Key 在第二步换取 Access Token 时,需要使用 Consumer Key,API Key Secret,Request Token 和 Request 而在第三步访问受限资源时,需要使用 Consumer Key,API Key Secret,Access Token 和 Access Token

Secret. Token Secret 进行签名. Secret 进行签名 举例说明: sha.getSignature("Request Toke&API Key Secret");

6 关于服务端如何生成 Request Token 以及 Access Token 等 说明

6.1 获取未授权的 Request Token 和密匙 tokenSecret

System.nanoTime()是返回 Long 类型的毫微秒的系统计时器的当前值. requesttToken=DigestUtils.md5Hex(consumer_key+ System.nanoTime()); tokenSecret=consumer_key + System.nanoTime() + requesttToken;

6.2

获取用户授权的 Request Token

获取用户授权的 request_token 可以不返回也可以使用上面的 requesttToken 和 tokenSecret

6.3

用授权的 Request Tok

en 换取 Access Token

accessToken= DigestUtils.md5Hex(consumer_key+ requestToken+ System.nanoTime());

accessSecret=DigestUtils.md5Hex(consumer_key+requestToken+System.nanoTime()+accessTokn);