Yahoo! OAuth導入分享

之前玩了使用第三方廠商導入OpenID，這個方式對於個人使用者來說很足夠了，不過對於公司企業來說，技術還是要掌握在自己手裡，所以又來研究這個Yahoo! OAuth。

我就不介紹OAuth的來由了，直接進入正題。

在開始之前，可以先看看OAuth Authorization Model，對於OAuth有一些說明。
Yahoo也提供了線上說明文件OAuth / OpenID Guides可以參考。
如果看著說明文件還是有問題，可以到YDN ForumsY的OAuth區詢問 (因為照Yahoo的說明做一定會有問題XD，有的地方有錯)
再來，就是看下面這張圖去按照流程開始接Yahoo! OAuth。

STEP 1 Sign Up and Get your API Key

首先，先到這邊申請Yahoo! API Key
https://developer.apps.yahoo.com/dashboard/createKey.html

申請完成後，你會在你的My Projects裡面看到目前沒有Project，所以需要創一個新的Project。

選擇的時候記得選擇"Open Application for the Yahoo! Homepage and My Yahoo!"，我一開始是選"Contacts, Mail, MyBlogLog, Social Directory, Status, Updates, Wreth"，不過發現認證過不了，之後重創成第一個選項的Application就可以了。

接下來，到Manage Domains，輸入你要使用Yahoo! OAuth的網域。

輸入後Yahoo會要你放一個指定名稱的html，放上去後再按Verify Domain去驗證就好。

STEP 2 Get a Request Token

詳細內容請參考Yahoo Doc Get a Request Token這篇。簡單來說，就是對https://api.login.yahoo.com/oauth/v2/get_request_token這個網址用POST或GET的方式(我都用POST)送出下列的參數：

Get a Request Token
參數名稱	說明
oauth_consumer_key	Project內的Consumer Key
oauth_nonce	一個隨便不重複的字串
oauth_signature_method	可為PLAINTEXT或HMAC-SHA1，我都用前者，oauth_signature_method的設定會影響oauth_signature這個參數資料的給法
oauth_signature	Project內的Consumer Secret，如果設為PLAINTEXT的話要在字串最後加上%26
oauth_timestamp	填入1970/1/1 00:00至今的秒數，Yahoo可允許正負600秒的差距
oauth_version	填入1.0
xoauth_lang_pref	語言選項，可不傳此參數
oauth_callback	取得Request Token後導向的網址

用使用台灣雅虎登入，語言請設成zh-Hant-TW，如果設zh-TW會變成用中國雅虎。

實際上呼叫的範例如下

https://api.login.yahoo.com/oauth/v2/get_request_token?oauth_consumer_key=dj0yJmk9YTNmSHJiNnh6aEpWJmQ9WVdrOVUyRlFRM0JzTm1zbWNHbzlNVEUxTnpBeE1EYzJNZy0tJnM9Y29uc3VtZXJzZWNyZXQmeD1hMA--&oauth_nonce=e43f20fe645b5d674f2c71e04289d2b05&oauth_signature_method=PLAINTEXT&oauth_signature=714185c632fcc18a2fa9644437ebe77df8916559%26&oauth_timestamp=127563433&oauth_version=1.0&xoauth_lang_pref=en-us&oauth_callback=http://doomdied.brinkster.bet/GetYahooOpenID.aspx

呼叫成功後，會傳回幾個參數(在windows下面除錯請使用類似wget的軟體測試)，不過只有oauth_token跟oauth_token_secret這兩個參數是後面認證需要的。

Step 3 Get User Approval

拿到oauth_token後，你必須將使用者導向這個網址，讓使用者用Yahoo的帳號登入認證，相關文件請參考Get User Authorization

https://api.login.yahoo.com/oauth/v2/request_auth?oauth_token=第一步取得的oauth_token

使用者登入並同意讓你的Project拉資料後，會導回在Step 2裡oauth_callback所給的網址，這時候會用QueryString的方式傳回oauth_token跟oauth_verifier這兩個之後會用到的參數。

Step 4 Exchange the Request Token for an Access Token

第三步拿到oauth_token跟oauth_verifier後，需要再取得Access Token才能與Yahoo API溝通，而這個步驟的目的是取得Access Token，相關文件請參考Exchange the Request Token and OAuth Verifier for an Access Token。
這個步驟也是使用GET或POST傳值給下面這個位址
https://api.login.yahoo.com/oauth/v2/get_token
參數如下:

Exchange the Request Token for an Access Token
參數名稱	說明
oauth_consumer_key	Project內的Consumer Key
oauth_signature_method	如Step 2所述，可為PLAINTEXT或HMAC-SHA1
oauth_nonce	一個隨便不重複的字串
oauth_signature	Project內的Consumer Secret加上Step 2接到的oauth_token_secret，如果設為PLAINTEXT的話要在Consumer Secret最後加上%26 (*)
oauth_timestamp	填入1970/1/1 00:00至今的秒數，Yahoo可允許正負600秒的差距
oauth_verifier	填入Step 3使用者認證後導回所傳的oauth_verifier
oauth_version	填入1.0
oauth_token	填入Step 3使用者認證後導回所傳的oauth_token

*:oauth_signature這邊容易出錯，記得是Consumer Secret接%26接oauth_token_secret的字串 (若設定為PLAINTEXT)

實際上呼叫的範例如下

https://api.login.yahoo.com/oauth/v2/get_token?oauth_consumer_key=dj0yJmk9YTNmSHJiNnh6aEpWJmQ9WVdrOVUyRlFRM0JzTm1zbWNHbzlNVEUxTnpBeE1EYzJNZy0tJnM9Y29uc3VtZXJzZWNyZXQmeD1hMA--&oauth_signature_method=PLAINTEXT&oauth_nonce=e43f20fe645b5d674f2c71e04289d2b05&oauth_signature=714185c632fcc18a2fa9644437ebe77df8916559%26
21a2e43f20fe645b5d674f2c71e04289d2b05352&oauth_timestamp=127563433&oauth_verifier=e3snmk&oauth_version=1.0&oauth_token=khey4pe

呼叫成功後回傳幾個參數，列表如下

Access Token Return
參數名稱	說明
oauth_token	Access Token，Step 5 或呼叫其他Yahoo! API可用
oauth_token_secret	對應Access Token的秘鑰，用於auth_signature，Step 5 也需要用到
oauth_session_handle	用於更新Access Token(Step 5)時的認證碼
oauth_expires_in	Access Token有效時間，通常是寫3600(秒)
oauth_authorization_expires_in	Access Token將於何時失效，以timestamp型式顯示
xoauth_yahoo_guid	Yahoo使用者的唯一識別值，也是本次OAuth的目的

以本次要導入Yahoo OAuth來說，取得xoauth_yahoo_guid就可以識別出玩家了(因為每個yahoo帳號的xoauth_yahoo_guid是不一樣的)，所以之後就可以拿這個值去做其他的運用了，不過為了完整，我還是把下面Step 5也打完。

Step 5 Refresh the Access Token

在Step 4 取得的Access Token可用於語其他Yahoo! API溝通，但是這個Access Token是有時間性的，超過了時間後就無法使用，所以要用Step 5的功能去更新Access Token，相關文件請見Refresh the Access Token。

這個步驟也是使用GET或POST傳值給下面這個位址
https://api.login.yahoo.com/oauth/v2/get_token
參數如下:

Refresh the Access Token
參數名稱	說明
oauth_nonce	一個隨便不重複的字串
oauth_consumer_key	Project內的Consumer Key
oauth_signature_method	如Step 2所述，可為PLAINTEXT或HMAC-SHA1
oauth_signature	Project內的Consumer Secret加上Step 4接到的oauth_token_secret，如果設為PLAINTEXT的話要在Consumer Secret最後加上%26 (*)
oauth_timestamp	填入1970/1/1 00:00至今的秒數，Yahoo可允許正負600秒的差距
oauth_version	填入1.0
oauth_token	填入Step 4所接到的oauth_token(Access Token) (**)
oauth_session_handle	填入Step 4所接到的oauth_session_handle

*:文件上對於oauth_signature此欄的說明"The concatenated Shared Secret (Consumer Secret) and Token Secret separated by an "&" character."有誤，實際上不用加上"&"，而是與Step 4一樣，Consumer Secret字串後接上%26再接上Step 4所收的oauth_token_secret。
**:這邊填入的oauth_token是Step 4傳回時所收的很長那一串oauth_token(Access Token)

成功後獲得的回傳結構與Step 4 一樣，這邊就不在贅述。

The End

這次弄Yahoo! OAuth其實花了我不少時間，雖然後來覺得資料還蠻詳細的，不過光要找到怎麼開始就找了很久，開始後的除錯也弄得很頭大，還好後來用了wget才看的到錯誤碼，在windows平台上用久了，真的不怎麼容易上手這個。

然後Yahoo OAuth的文件雖然寫的蠻清楚的，但是有些細節還是很容易讓人搞糊塗，看看論壇上的問題幾乎都是我也遇到過的，希望把這些東西寫出來之後，可以讓有需要的人節省一些時間，我估計可以省下九成除錯浪費的時間XD