簡單易懂的 OAuth 2.0

ᾏẪၞ׭֥ OAuth 2
⇯௾
2013/11/26, Ruby Tuesday Taipei #27
(?)

View Slide

• ⇯௾č⊫ტӵĎ
• Rails Developer at KKBOX, working at the KKTIX team
• chitsaou, @yorkxin, blog.yorkxin.org

View Slide

Today’s Target
• ୆὜ᆩ֡ OAuth 2 Protocol ᄸ喁஝
• ୆὜ु֤׭ 99% ࠎᧄ OAuth 2 ֻ֥೘ٚ API ໓ࡱ
• ୆὜ᆩ֡ᄸ喁Ⴈ OAuth 2 ⅞୆֥ API

View Slide

Agenda
• OAuth 2 ൞മ喁ĤॖၛଦῲἓખĤ
• OAuth 2 ๙⇫⇐קᄸ喁஝
• ⚧ᄯ OAuth 2 Provider ֥ٚم
• ֻ၂ՑႨ Rails + Grape API ᆜކ OAuth 2 ࣼഈ൭

View Slide

OAuth 2 ൞മ喁Ĥݺӹ⁯Ĥ

View Slide

OAuth 2.0
• ಆ଀ “The OAuth 2.0 Authorization Framework”
• Authorization (n.) ൱⃴

View Slide

ದ ๩Ἶ¯¯ ൱⃴ἡ ӱൔ
䪌w୆ॖၛಀ۵ଛᅟଦ໡֥⊷ਘx

View Slide

ದ ๩Ἶ¯¯ ൱⃴ἡ ӱൔ
User

View Slide

ದ ๩Ἶ¯¯ ൱⃴ἡ ӱൔ
User App

View Slide

ದ ๩Ἶ¯¯ ൱⃴ἡ ӱൔ
User
Website
App

View Slide

ದ ๩Ἶ¯¯ ൱⃴ἡ ӱൔ
User
Website
App
API

View Slide

ದ ๩Ἶ¯¯ ൱⃴ἡ ӱൔ
User
Website
App
API
Sounds Familiar?

View Slide

You
Facebook

API
ದ ๩Ἶ¯¯ ൱⃴ἡ ӱൔ
Sounds Familiar?

View Slide

The Old-School Way…
• App ေ୆℻ೆ≷ὂૡ⁫đὕ℥ૼ҂὜⁙۞
• ୆ေྐ಩ App ҂὜ଦ୆֥ૡ⁫⁙۞
• ࣼෘ App ޓܭđФἓሼὕ൞㢻ࣷ
• ҂ܵ୆ྐ҂ྐđ໡ّᆞ൞҂ྐ……

View Slide

OAuth ೂޅࢳ㢯≾ἠ↜ⅳ
• ↌ᅟิ܂ܲٚࢸ૫đ⃸୆ॖၛ൱⃴ӱൔ൐Ⴈ⊷ਘ
• ӱൔթ֥൞ Token ط٤≷ὂૡ⁫ 
္Ⴈ Token ಀյ API
• Token ॖၛἲקթ౼ữ↏čscopes, ೂğݺႶਙіĎ
• Token Ⴕ௹ཋط౏ॖၛ⅗ℭӜ⇍č҂ஃФἓሼĎ

View Slide

OAuth 2 䥰૫֥࢘೤
• Resource Owner - ⊷ਘ∭Ⴕᆀđ๙ӈ൞ದ (User)
• Client - ࠧ App đေթ౼ User ֥⊷ਘ֥ӱൔ
• Authorization Server - ⊺ܵ၂్൱⃴൙↩
• Resource Server - Client ạ≾䥰ଦ⊷ਘđࠧ API

View Slide

ದ ๩Ἶ¯¯ ൱⃴ἡ ӱൔ
You
Facebook

API

View Slide

ದ ๩Ἶ¯¯ ൱⃴ἡ ӱൔ
You
Facebook

API
Resource
Owner
Client
Resource Server
Authorization
Server

View Slide

Resource Owner

View Slide

Resource Owner = User
• ࣼ൞୆↌ᅟ֥ User
• API ঘ֥֞൞۵ User ႵἬ֥⊷ਘ
• ২ೂݺႶ଀Ẫaྐࡱ⤨ಸ
• ൱⃴с⇜ῂႮЧದ⃤ሱ⃷⃾

View Slide

Resource Owner = Client
• ≾⊕౦㣐㢻Ⴕದ֥թᄝb
• ২ğ஁܄Ῐ⊷ਘ
• Twitter Ẁ㬪 App-Only Authorization
• Facebook Ẁ㬪 App Access Token

View Slide

Client

View Slide

Client
• User ൱⃴ἡֻ೘ٚӱൔđ≾ἠӱൔࣼ൞ Client
• ২ğFacebook ഈ֥䵔↰a൭Ὠഈ֥ App
• ܲٚӱൔ္ෘč২ೂ൭Ὠ App aም૫ AppĎ

View Slide

Client с⇜൙༵䩏⤳
• “Client Registration”
• Client ID
• Client Secret čℶ㬪ૡ⁫Ď
• Redirect URI ← ≾ἠޓᇗေ

View Slide

View Slide

Client ID

View Slide

Client Secret

View Slide

Redirect URI

View Slide

Redirect URI
• User Чದ⃤ሱ⃷⃾ᆭᗥđْ߭᾵ݔ֞ Client
• ေ൙༵ᆷקđ೏҂၂ᇁ≣҂ॖ Redirect Ἶಀ
• ॖၛᆷק؟⊾đ֌๙ӈ൞၂⊾đࠇ൞Ῐⅽ၂ᇁ
• ቋݺ൞ HTTPS č҂ルᇅđ২ೂ൭Ὠ App ࣼḰ҂֞Ď

View Slide

Redirect URI
• https://kktix.com/users/auth/facebook/callback
• http://kktix.dev/users/auth/facebook/callback
• kktix-app:oauth2/callback

View Slide

Public v.s. Confidential Client
• ۴ῌwି҂ିЌὊ⊷ਘxῲ⃯ٳ
• Confidential - Server-Side Application
• Public - ൭Ὠ App / ም૫ӱൔ / JavaScript App /
Browser Extension

View Slide

Client Authorization (⃾⊈)
• ԛൕ Client ID + Secret ཟ Auth. Server ⃾⊈ሱ࠭
• ္ࣼ൞䪌 Client ေ֨ೆ֞ Auth. Server
• ᆺℳႨ Confidential Client

View Slide

Client
• Ⴕ ID / Secret Ⴈᧄ⃾⊈
• Ⴈ Redirect URI ⃷Ќ⏟´ఖ⊨ᆶ֞ᆞ⃷֥ Client
• Public / Confidential Ⴕ۲ሱℳႨ֥൱⃴ੀӱ

View Slide

Endpoints

View Slide

Endpoints
• Authorization Endpoint - Ⴈῲἡ User Чದ⃷⃾൱⃴
• Token Endpoint - Ⴈῲ⃸ Client ౼֤ᆇᆞ֥ Token
• Redirection Endpoint - Client Ⴈῲ൬⊷ਘႨ

View Slide

Authorization Endpoint
• ἡ User Чದ⃷⃾൱⃴
• ൞၂ἠ↌∉
• ଦ֥֞൞ “Grant” č൱⃴⊯Ďط҂൞ Token
• User ճڭᆭᗥđ὜⊨߭ Client ֥ Redirect URI

View Slide

Token Endpoint
• ἡ Client ౼֤ᆇᆞ֥ Token
• JSON API Ὠྀ߄ࢸ૫đ↥↌∉

View Slide

Redirection Endpoint
• Ⴈῲạ⏟´ఖࢤ൬ Auth. Server ῲ֥⊷ਘ
• Ῐᄝ Client ط҂൞ Auth. Server
• Client 䩏⤳ℭေ⇔֥ “Callback URL”
• Auth. Server ὜⇼⊈ Redirect URI ൞ڎཌྷژҌ⊨ᆶ

View Slide

SSL! SSL! SSL!
• Auth. Server ഈ૫֥ Endpoints с⇜ഈ HTTPS
• Client с⇜⇼⊈ SSL Certificate ൞ڎކ۬
• Client Redirection Endpoint ҂ルᇅđ֌ିഈቋݺഈ 
↌ᅟ → ቋݺഈ 
൭Ὠ / ም૫ App → 㢻Ḱمॖၛ҂ေഈ

View Slide

Resource Server

View Slide

Resource Server
• Client с⇜ԛൕ Token ҌିΆಀଦ⊷ਘ
• Client ᆺေԛൕ Token ࣼିΆಀଦ⊷ਘ
• ॖၛႨ Scope ཋᇅ Token ିⴺ౼Ⴈ֥⊷ਘữ↏

View Slide

Resource Server
• Password-Free API
• Login via YourWebsite™

View Slide

OAuth 2 Protocol ᄸ喁஝

View Slide

wᾏẪάđồ Spec άx*
*ս䩽҂൞Чದ෮མ֥≾喁ᾏẪ
ݠ`ದ

View Slide

• RFC 6749: The OAuth 2.0 Authorization Framework
• 77 pages (PDF)
• RFC 6750: The OAuth 2.0 Authorization Framework:
Bearer Token Usage
• 19 pages (PDF)
tl;dr

View Slide

• Ⴈಀ 3 ἠ‎Ϩ
• ⇔ਔ 13 ௉ṁὸ →
/me ၘồb

View Slide

OAuth 2.0 Spec(s)
• RFC 6749 - ק∕∻ Token ނứႵἬ֥ Protocol
• RFC 6750 - ק∕wBearer Tokenxᄸ喁Ⴈ

View Slide

RFC 6749: OAuth 2 Protocol
• ק∕ਔ OAuth 2 ֥࢘೤a޺ọٚൔ
• ק∕ਔ⊷ਘႵଧུaᄸ喁஝
• ק∕ਔނứa㍤ứ Token ֥֩ Protocol
• ἲ὎ਔ 4 ⊕ӈᾖwℳކ൐Ⴈ OAuth 2 ֥ੀӱx

View Slide

RFC 6750: Bearer Token
• RFC 6749 ᆺἲק൱⃴ٚൔđ㢻ἲק API ᄸ喁Ẳ
• RFC 6750 ק∕၂⊕ࢡቓ “Bearer” ֥ Token Type
• ۲⊕ type Ⴕ҂๝Ẳمđ Bearer ൞ᆰࢤ == ᾋҰ
• ၂ओὐࢳℴğwᆰࢤଦῲࣼିႨđ҂Ⴈ⃐ῲ⃐ಀx

View Slide

Parameters & Data

View Slide

Client ID / Secret
• Ⴈᧄ Client ⃾⊈čClient ֨ೆ֞ Auth. ServerĎ
• 䩏⤳֥ℭީứἡđ⁙⁫ࣼྛ
• HTTP Basic Auth ࠇЇᄝ Form 䥰૫č࣌Ⴈ URLĎ

View Slide

HTTP Basic Auth
ID = abc, Secret = 123
abc:123
concat with `:`
YWJjOjEyMw==
base64()
Authorization: Basic YWJjOjEyMw==
Basic Auth Header

View Slide

Token(s)
• Access Token - յ API Ⴈ֥
• Refresh Token - Access Token Ἶ௹ॖၛ㍤ứྍ֥

View Slide

Access Token
• ཟ Resource Server ေ⊷ਘđႨ Access Token
• ॖၛḳ၂⊾ Scope
• ॖၛ℟௹ཋđॖၛӜ⇍ (Revoke)
• ൱⃴ੀӱ֥ଢṌࣼ൞ေଦ֞ Access Token

View Slide

Refresh Token
• ㍤ứ Access Token Ⴈđᆺ὜ẖ֞ Auth. Server
• ḳק၂ἠ Access Tokenđ⅗ Access Token ၂ఏނứ
• ႨἾࣼാི 
ྍ֥ Access Token ὜ḳྍ֥ Refresh Token

View Slide

Scopes
• Ⴈῲіൕwॖၛթ౼ଧུ⊷ਘx֥⃴ཋữ↏
• ೂwݺႶ଀Ẫxawཌྷோx
• ॖၛ A cover B đằಖ Set ൞ቋᾏẪ֥ቓم

View Slide

Scopes
• ണ⃪൱⃴ℭॖၛἲק 
w၂קေἡxࠇw㢻ἡࣼ≁℟ᆴx
• Ⴈॢ۬’ఏῲđ২ೂ "friends_list photos"
• ֌ޓ؟↌ᅟႨ׹ὂ `,`
△

View Slide

State
• Ⴈῲٝᆸ CSRF ۾ὧ
• Client 㲗 Browser 㲗 Auth. Server ൞ޓາ↿ˀ
• State ẖ֞ Auth. Server ࣼေჰٿ҂ọْ߭
• Client ⇼⊈ᆭ
• ⁙⁫ᆴࣼྛđ္ॖၛႨ HMAC ⃐

View Slide

Protocol: ೂޅ౼֤൱⃴
ạ Client ֥ℶ࢘

View Slide

౼֤൱⃴֥ੀӱ
1. Client ཟ Res. Owner ౼֤ “Grant” č൱⃴⊯Ď
2. Client Ⴈ “Grant” ཟ Authorization Server ㍤ Token
3. Token ଦ֞ਔđॖၛಀյ API
ᆜἠ Protocol ቋₒ֥ᄝ≾䥰

View Slide

ቋӈᾖ֥ Scenario
Ⴕ↌ᅟ Facebook đ୆༐ຬᄝପഈ૫֥ User
 
ἡ୆֥↌ᅟ⃴ཋđॖၛồ౼ପ User ֥⊷ਘ
Resource Owner
Client Token Resource Server
๩Ἶ Facebook ֥ Authorization Server

View Slide

նࡅ׻ԱἾ
※Ⴈ Library Ա

View Slide

“Authorization Code Grant Flow”

View Slide

Auth Code Grant Flow
• Grant ൞ऎⅴ֥ሳԱđẀቔ Code
• ླေῂἾ Browser
• ℳႨᧄw↌ᅟx≾⊕ Client

View Slide

Resource
Owner
Client
!
Authorization
Server
※Ӓሱ spec

View Slide

Resource
Owner
Browser
Client
!
Authorization
Server
※Ӓሱ spec

View Slide

Resource
Owner
Browser
Client
!
Authorization
Server
※Ӓሱ spec
Authorization
Endpoint
Token
Endpoint
Redirection
Endpoint

View Slide

Resource
Owner
Browser
Client
!
Authorization
Server
(A)
(A) ID, Redirect URI, Scope, State
※Ӓሱ spec
Authorization
Endpoint
Token
Endpoint
Redirection
Endpoint

View Slide

Resource
Owner
Browser
Client
!
Authorization
Server
(A)
(B)
(B) ↜ Resource Owner
※Ӓሱ spec
Authorization
Endpoint
Token
Endpoint
Redirection
Endpoint

View Slide

Resource
Owner
Browser
Client
!
Authorization
Server
(A)
(B)
(C) Grant Code, Scope, State
※Ӓሱ spec
Authorization
Endpoint
Token
Endpoint
Redirection
Endpoint

View Slide

Resource
Owner
Browser
Client
!
Authorization
Server
(A)
(B)
(D) Grant Code, Client Auth
※Ӓሱ spec
Authorization
Endpoint
Token
Endpoint
Redirection
Endpoint

View Slide

Resource
Owner
Browser
Client
!
Authorization
Server
(A)
(B)
(D) Grant Code, Client Auth
(E) Token
※Ӓሱ spec
Authorization
Endpoint
Token
Endpoint
Redirection
Endpoint

View Slide

(A) ứԛ൱⃴ണ⃪
Client Ῐ၂ἠ↌ᆶἡ User ề
Login with Facebook

View Slide

https://graph.facebook.com/oauth/authorize?
response_type=code&client_id=567672586646825&
redirect_uri=http%3A%2F%2Flocalhost
%3A3000%2Fusers%2Fauth%2Ffacebook
%2Fcallback&state=446c63696b24b4b6687cdff62ea
bce3a9c9d6333d7c807e6&scope=email
(GET Request)

View Slide

response_type=code
&client_id=567672586646825
&redirect_uri=http://localhost:3000/users/
auth/facebook/callback
&state=446c63696b24b4b6687cdff62eabce3a9c9d63
33d7c807e6
&scope=email

View Slide

response_type=code
&client_id=567672586646825
33d7c807e6
&scope=email

View Slide

response_type=code
&client_id=567672586646825
33d7c807e6
&scope=email
іൕ Authorization Code Grant Flow

View Slide

response_type=code
&client_id=567672586646825
33d7c807e6
&scope=email
Client ID

View Slide

response_type=code
&client_id=567672586646825
33d7c807e6
&scope=email
Client ID
Redirect URI

View Slide

response_type=code
&client_id=567672586646825
33d7c807e6
&scope=email
Client ID
Redirect URI
Client ֥ State čٝ CSRF Ď

View Slide

response_type=code
&client_id=567672586646825
33d7c807e6
&scope=email
Client ID
Redirect URI
མေ⃪౰֥⃴ཋữ↏čScopesĎ

View Slide

Authorization Server ֥ọቔ
1. ۴ῌ Client ID ᅳ Client
2. ⃷⃾ Redirect URI ۵൙༵䩏⤳֥ཌྷژ
• ೏҂ᆞ⃷≣ေ₵ấ↪đ҂ॖ⊨߭ἐ URI
3. ⃷⃾མണ⃪֥ scope ᆞ⃷č۬ൔa⤨ಸ֩Ď
4. 㢻↜ⅳࣼ↜ Resource Owner ေ҂ေ൱⃴ (B)

View Slide

(B) Auth. Server ↜ Res. Owner

View Slide

• ೏ᄍ⇝đ≣⊨߭ Client đڸഈ Grant Code
• ೏҂ᄍ⇝đ≣⊨߭ Client đ❣ڸഈấ↪⇫༏
• ೏἗἗Ⴕẖ state Ἶῲđ≣ჰٿ҂ọڸഈ

View Slide

(C) Client ൬֞ Grant Code
(GET Request)

View Slide

HTTP/1.1 302 Found
Location: http://localhost:3000/users/auth/
facebook/callback?
code=AQABIWdeO3miePq0uH2VCUvhGr-
voXz3zunrCiX5Bz9IFF8m82bmP(...)&state=446c636
96b24b4b6687cdff62eabce3a9c9d6333d7c807e6

View Slide

http://localhost:3000/users/auth/facebook/
callback?
voXz3zunrCiX5Bz9IFF8m82bmP(...)
33d7c807e6

View Slide

callback?
33d7c807e6

View Slide

callback?
33d7c807e6
൱⃴⊯ (Grant Code)

View Slide

callback?
33d7c807e6
൱⃴⊯ (Grant Code)
ჰٿ҂ọ֥ State ᆴ

View Slide

Client ֥ọቔ
• ༵ᾋҰ state ۵ session 䥰૫թ֥Ⴕ㢻Ⴕ၂ᇁ
• 㢻↜ⅳࣼಀ㍤ Token ਔ

View Slide

(D) ଦ Code ㍤ Token
• Client ᄝᗥ෻ቓ≾ࡱ൙
• POST ֞ Auth. Server ֥ Token Endpoint ㍤ Token
• Client Authentication
• grant_type=code, code, redirect_uri,
client_id (Ᾱ Public Client)

View Slide

POST /oauth/access_token HTTP/1.1 
Host: graph.facebook.com 
Authorization: Basic YWJjOjEyMw== 
Content-Type: application/x-www-form-
urlencoded 
 
grant_type=authorization_code 
 
&code=AQABIWdeO3miePq0uH2VCUvhGr-
voXz3zunrCiX5Bz9IFF8m82bmP(...) 
 
&redirect_uri=http%3A%2F%2Flocalhost
%3A3000%2Fusers%2Fauth%2Ffacebook%2Fcallback
※ ൙ℯഈ Facebook Ⴈ GET đ҂ކṌ⊵đ༯ⅾ⃪ሱྛₔṘ

View Slide

urlencoded 
 
 
 
Token Endpoint

View Slide

urlencoded 
 
 
 
Token Endpoint
Client Authentication

View Slide

urlencoded 
 
 
 
Token Endpoint
іൕw໡ଦ֥֞൱⃴⊯൞ Grant Codex

View Slide

urlencoded 
 
 
 
Token Endpoint
Grant Code

View Slide

urlencoded 
 
 
 
Token Endpoint
Grant Code
ჰ Redirect URI

View Slide

• ⃷⃾ Client Authentication (ID / Secret) ᆞ⃷
• ᅳ֞ἐ Grant Code đ⃷⃾ః Redirect URI ၂ଆ၂∄
• 㢻↜ⅳ֥ὐࣼứ Token

View Slide

(E) ứ Token
• Client ֥ Token Request ֥ Response
• ൞ JSON Response
• ॖၛ၂⟸ứ Refresh Token
• User ൱⃴֥ Scope ೏∻ണ⃪ℭ҂၂ᇁ≣ေڸഈ

View Slide

HTTP/1.1 200 OK 
Content-Type: application/json;charset=UTF-8 
Cache-Control: no-store 
Pragma: no-cache 
{ 
"access_token":"2YotnFZFEjr1zCsicMWpAA", 
"token_type":"Bearer", 
"expires_in":3600, 
"refresh_token":"tGzv3JOkF0XG5Qx2TlKWIA", 
"scopes":"email" 
}

View Slide

HTTP/1.1 200 OK 
Pragma: no-cache 
{ 
"scopes":"email" 
}
Access Token

View Slide

HTTP/1.1 200 OK 
Pragma: no-cache 
{ 
"scopes":"email" 
}
Access Token
іൕ≾ἠ Token ൞ Bearer Token

View Slide

HTTP/1.1 200 OK 
Pragma: no-cache 
{ 
"scopes":"email" 
}
Access Token
3600 ૰ᆭᗥἾ௹

View Slide

HTTP/1.1 200 OK 
Pragma: no-cache 
{ 
"scopes":"email" 
}
Access Token
3600 ૰ᆭᗥἾ௹
Access Token Ớ∣֥ Refresh Token

View Slide

HTTP/1.1 200 OK 
Pragma: no-cache 
{ 
"scopes":"email" 
}
Access Token
3600 ૰ᆭᗥἾ௹
Access Token Ớ∣֥ Refresh Token
೏ scope ∻ണ⃪ℭ
҂၂ᇁ≣ေڸഈ

View Slide

൭Ὠ App / ም૫ App
• ℶ㬪 Public đClient Authentication ҂ॖྐ
• Token Request ေڸഈ Client ID 
⃷Ќ Token ứἡᆞ⃷֥ Client
• App ⅹܥק URI đೂ 
kktix-app:oauth2-callback

View Slide

What about JavaScript App
• “User-Agent-Based Client”
• Public Client
• Redirect Endpoint ္㢻Ḱمⅹሱị Protocol
• Auth. Code Grant Flow ҂ॖႨđᄸ喁ḰĤ

View Slide

“Implicit Grant Flow”

View Slide

Implicit Grant Flow
• ⊦⁽ἡ Public Client Ⴈ
• Grant ҂ẖ֞ Client đᆰࢤứ Token
• ҂ῂἾ Token Endpoint
• ứ֥ Token ๙ӈ൞؋ི௹đࢆ֮Ф๦֥ἀ↿
• ҂ἡ Refresh TokenđἾ௹ᇗྍ஝ണ⃪ੀӱ

View Slide

Resource
Owner
Client (JS)
!
Authorization
Server
※Ӓሱ spec

View Slide

Resource
Owner
Browser
Client (JS)
!
Authorization
Server
※Ӓሱ spec

View Slide

Resource
Owner
Browser
Client (JS)
!
Authorization
Server
※Ӓሱ spec
Client’ 
(Web Server)

View Slide

Resource
Owner
Browser
Client (JS)
!
Authorization
Server
※Ӓሱ spec
Authorization
Endpoint
Client’ 
(Web Server)
Redirection
Endpoint

View Slide

Resource
Owner
Browser
Client (JS)
!
Authorization
Server
(A)
※Ӓሱ spec
Authorization
Endpoint
Client’ 
(Web Server)
Redirection
Endpoint

View Slide

Resource
Owner
Browser
Client (JS)
!
Authorization
Server
(A)
(B)
※Ӓሱ spec
Authorization
Endpoint
Client’ 
(Web Server)
Redirection
Endpoint

View Slide

Resource
Owner
Browser
Client (JS)
!
Authorization
Server
(A)
(B)
(C) Token (in Frag.), Scope, State
※Ӓሱ spec
Authorization
Endpoint
Client’ 
(Web Server)
Redirection
Endpoint

View Slide

Resource
Owner
Browser
Client (JS)
!
Authorization
Server
(A)
(B)
※Ӓሱ spec
Authorization
Endpoint
Client’ 
(Web Server)
Redirection
Endpoint
(D) GET Redirect URI (no Token)

View Slide

Resource
Owner
Browser
Client (JS)
!
Authorization
Server
(A)
(B)
(E) JavaScript (to Decode Token)
※Ӓሱ spec
Authorization
Endpoint
Client’ 
(Web Server)
Redirection
Endpoint

View Slide

Resource
Owner
Browser
Client (JS)
!
Authorization
Server
(A)
(B)
※Ӓሱ spec
Authorization
Endpoint
Client’ 
(Web Server)
Redirection
Endpoint
(F)

View Slide

Resource
Owner
Browser
Client (JS)
!
Authorization
Server
(A)
(B)
※Ӓሱ spec
Authorization
Endpoint
Client’ 
(Web Server)
Redirection
Endpoint
(G) Assign Access Token
(F)

View Slide

View Slide

(C) ~ (G) ޽ളസଊℿ
• (C) Auth. Server ࢡ Browser ⊨߭ Redirect URI
• https://client.com/oauth2/callback#access_token=…
• (D) Browser ὜ಀ GET ἐ URL đ֌҂ݣ # č฿ྟĎ
• Token ሱọЌ਽ᄝ Browser ֥ Fragment Part 䥰૫

View Slide

(C) ~ (G) ޽ളസଊℿ
• (E) ᄜ❟߭၂ἠ JavaScript Ⴈῲࢳԛ # 䥰૫֥ Token
• (F) Browser ሱọ run ≾ἠ JavaScript ࢳԛ Token
• (G) Ϝࢳԛῲ֥ Token ❟ἡ JavaScript App

View Slide

෮ၛ㬪൉喁ླေ Client’ ٳദ
• JavaScript ҂ିῘ Redirection Endpoint 
෮ၛႨ Web Server Ῐ
• 䥰૫ࣼ൞၂ἠ JavaScript code Ⴈῲࢳԛ Token 
❣ẖἡ JavaScript App (ᆇ Client)

View Slide

response_type=token
&client_id=567672586646825
&redirect_uri=http://localhost:3001/jsapp/
facebook/callback
33d7c807e6
&scope=email

View Slide

response_type=token
&client_id=567672586646825
facebook/callback
33d7c807e6
&scope=email

View Slide

response_type=token
&client_id=567672586646825
facebook/callback
33d7c807e6
&scope=email
іൕ Implicit Grant Flow

View Slide

response_type=token
&client_id=567672586646825
facebook/callback
33d7c807e6
&scope=email
Client ID

View Slide

response_type=token
&client_id=567672586646825
facebook/callback
33d7c807e6
&scope=email
Client ID
Redirect URI

View Slide

HTTP/1.1 302 Found
Location: http://localhost:3001/jsapp/
facebook/
callback#access_token=AQABIWdeO3miePq0uH2VCUv
hGr(...)&state=446c63696b24b4b6687cdff62eabce
3a9c9d6333d7c807e6
&token_type=bearer&expires_in=3600

View Slide

http://localhost:3000/jsapp/facebook/
callback#
token=AQABIWdeO3miePq0uH2VCUvhGr-
33d7c807e6
&token_type=Bearer
&expires_in=3600

View Slide

callback#
33d7c807e6
&token_type=Bearer
&expires_in=3600

View Slide

callback#
33d7c807e6
&token_type=Bearer
&expires_in=3600
Access Token

View Slide

callback#
33d7c807e6
&token_type=Bearer
&expires_in=3600
Access Token
3600 ૰ᆭᗥἾ௹

View Slide

Redirection Endpoint ֥⤨ಸ
 <br/>var access_token = [extract token from frag]; <br/>// store token in local storage or cookie <br/>

View Slide

Implicit Grant Flow Usage
• Facebook JavaScript SDK
• ൭Ὠ App aም૫ App ္ℳႨ 
Facebook: WebView ᾄⅹܥק Redirect URI 
ሂԛ #access_token

View Slide

ห⦁ᇿၩ൙⇊
• 㬪ࢆ֮ Token Ф๦ἀ↿đ๙ӈ὜ứ؋ི௹֥ Token
• ၹ㬪ॖି⢔ᄯ Token 刈ἡ Client đ෮ၛс⇜⇼⊈ᆭ
• Facebook: “Token Debug Endpoint”

View Slide

What if ሱ㸗ሱႨĤ
• ሱ࠭⇔֥ script མေႨ Token ಀյ API
• Server App ၘῂթਔ≷ὂૡ⁫đམڿӮ OAuth 2

View Slide

“Resource Owner Password
Credentials Grant Flow”

View Slide

Resource
Owner
Client
!
Authorization
Server
※Ӓሱ spec

View Slide

Resource
Owner
Client
!
Authorization
Server
※Ӓሱ spec
Token
Endpoint

View Slide

Resource
Owner
Client
!
Authorization
Server
※Ӓሱ spec
Token
Endpoint
(A) Username, Password

View Slide

Resource
Owner
Client
!
Authorization
Server
(B) Client Auth,
Username, Password, Scopes
※Ӓሱ spec
Token
Endpoint

View Slide

Resource
Owner
Client
!
Authorization
Server
(B) Client Auth,
Username, Password, Scopes
(C) Token
※Ӓሱ spec
Token
Endpoint

View Slide

Resource Owner Password
Credentials Grant Flow
• ླေ൞ Resource Owner ۚ؇ྐῳ Client
• ቔ∊༢ⅼ⤨ࡹ֥∣ႨӱൔčOS X ֥ Twitter ᆜކĎ
• ܲٚ∣ႨӱൔčGitHub.appĎ
• ౏ః෰⦁֥ੀӱ׻҂ℳႨ

View Slide

Resource Owner Password
Credentials Grant Flow
• No “state” ၹ㬪҂ῂἾ Browser
• No “Redirect URI” ၹ㬪㢻Ⴕ redirection
• ᆰࢤ POST ಀ Token Endpoint ଦ Token

View Slide

POST /token HTTP/1.1 
Host: oauth.example.com 
urlencoded 
 
grant_type=password 
 
&username=chitsaou 
&password=12345678 
 
&scope=email

View Slide

urlencoded 
 
 
 
&scope=email
Token Endpoint

View Slide

urlencoded 
 
 
 
&scope=email
Token Endpoint
іൕw໡ଦ֥֞൱⃴⊯൞ 
User ֥ Passwordx

View Slide

urlencoded 
 
 
 
&scope=email
Token Endpoint
іൕw໡ଦ֥֞൱⃴⊯൞ 
User ֥ Passwordx
Credentials

View Slide

Password ֥↜ⅳ
• Token Endpoint ေٝВ৯௥ࢳ
• Client ҂ሙϜ≷ૡթఏῲ

View Slide

What if ҂ླေ UserĤ
• ᆺթ౼܄Ῐ⊷ਘ
• Data-Mining Twitter Public Timeline

View Slide

“Client Credentials Grant Flow”

View Slide

Client
!
Authorization
Server
※Ӓሱ spec

View Slide

Client
!
Authorization
Server
※Ӓሱ spec
Token
Endpoint

View Slide

Client
!
Authorization
Server
(A) Client Auth, Scopes
※Ӓሱ spec
Token
Endpoint

View Slide

Client
!
Authorization
Server
(A) Client Auth, Scopes
(B) Token
※Ӓሱ spec
Token
Endpoint

View Slide

urlencoded 
 
grant_type=client_credentials 
 
&scope=search_timeline

View Slide

urlencoded 
 
 
Token Endpoint

View Slide

urlencoded 
 
 
Token Endpoint
іൕw໡ Client ေണ⃪ Token ሱႨx

View Slide

4 built-in grant flows
• Authorization Code
• Implicit
• Resource Owner Password Credentials
• Client Credentials

View Slide

ứളấ↪ℭ֥߭∣ٚൔ

View Slide

Errors on Authorization Endpoint

View Slide

Errors on Authorization Endpoint
1. ⃾҂ԛ ClientaRedirect URI ҂ژ
2. Ṛ⅂ẖấ / Authorization Server 㢻ℯቔଖུۿି
3. Resource Owner ऋ䌉൱⃴
4. Internal Server Error

View Slide

Client ⃾҂֤aRedirect URI ҂ژ
• Redirect URI 㢻ἡ / ҂ᆞ⃷ / 㢻൙༵䩏⤳
• ေℶ㬪۾ὧđ҂ॖၛ Redirect ֞ἐ Redirect URI
• ေิൕࣞۡ⇫༏ἡ Resource Owner

View Slide

ః෰ấ↪
• ေ⊨߭ Redirect URI ཟ Client ۡᆩấ↪
• ᄝ URI ᗥ૫ڸഈ error parameters
• Auth Code Grant Flow - Ⴈ Query ?error=...
• Implicit Grant Flow - Ⴈ Fragment #error=...

View Slide

Error Parameters
• error - Error Code đсแđ༯⇈
• error_description - ᾏẪ䪌ૼấ↪
• error_uri - ၂ἠ↌ᆶᆷ֞⇈↱䪌ૼ↌∉
• state - ẖ߭ Client ֥ state ჰᆴđᆭభႵἡࣼсแ
• ଖུὕ὜ἡ error_subcode čႭఃᇏἽ֥↌ᅟĎ

View Slide

callback?
error=access_denied 
 
&error_description=User Denies Authrization 
 
&error_uri=https://doc.example.com/... 
 
33d7c807e6

View Slide

callback?
 
 
 
33d7c807e6

View Slide

callback?
 
 
 
33d7c807e6
ấ↪⁫

View Slide

callback?
 
 
 
33d7c807e6
ấ↪⁫
ᾏඍấ↪൞൉喁

View Slide

callback?
 
 
 
33d7c807e6
ấ↪⁫
ु⇈↱䪌ૼ֥ URL

View Slide

callback?
 
 
 
33d7c807e6
# Implicit Flow: ㍤Ӯ Fragment Parameter

View Slide

error = Meaning
invalid_request
㢻ἡсေṚ⅂aἡਔ҂ᆞ⃷֥Ṛ⅂a 
ᇗ♶ἡṚ⅂aࠇః෰ჰၹẹᇁ↥مࢳồb
unauthorized_client
Client ҂ሙႨ≾⊕ Response Type 
ῲ౼֤ Authorization Codeb
unsupported_response_type
Authorization Server ҂ᆦჱ൐Ⴈ≾⊕
Response Typeb
invalid_scope
෮ေ౰֥ scope ҂ᆞ⃷a 
҂ૼa↥مࢳồb
Client ᄯӮ֥ấ↪

View Slide

error = Meaning
access_denied
Resource Owner ࠇ Authorization Owner 
ऋ䌉൱⃴֥ണ⃪b
൱⃴ാḮ

View Slide

error = Meaning
server_error
Authorization Server მ֞ၩຓ֥౦㣐ط 
↥مẕ৘⃪౰b
temporarily_unavailable
Authorization Server ӑ≘ࠇ→ྩᇏđ 
↥مẕ৘b
Authorization Server Internal Server Error

View Slide

error = Meaning
server_error
Authorization Server მ֞ၩຓ֥౦㣐ط 
↥مẕ৘⃪౰b
temporarily_unavailable
Authorization Server ӑ≘ࠇ→ྩᇏđ 
↥مẕ৘b
Q: 㬪൉喁҂ିႨ 500 ߭Ĥ
A: ၹ㬪 500 ҂ᆦჱ Location ⊨ᆶđerror ẖ҂߭ Client

View Slide

Errors on Token Endpoint

View Slide

Errors on Token Endpoint
1. Auth. Server ⃾҂֤ Client
2. Ṛ⅂ẖấ / Authorization Server 㢻ℯቔଖུۿି
3. ൱⃴⊯ (Grant) ҂ᆞ⃷
4. Internal Server Error

View Slide

߭∣ٚൔ
• ၂ੰЇΆ JSON ߭
• ๙ӈ߭ 400 Bad Request
• ೏ Client ⃾⊈ാḮ & Ⴈ Authorization Header ⃾⊈ 
→ ೖ WWW-Authenticate header

View Slide

Error Parameters (≅ Auth E.P.)
• error
• error_description
• error_uri
• ଖུὕ὜ἡ error_subcode čႭఃᇏἽ֥↌ᅟĎ
• No state (ၹ㬪㢻Ⴕ state ẖΆῲά)

View Slide

HTTP/1.1 401 Unauthorized 
WWW-Authenticate: Basic 
Pragma: no-cache 
{ 
"error":"invalid_client", 
"error_description":"Client Authentication
Failed", 
"error_uri":"https://doc.example.com/..." 
}

View Slide

Pragma: no-cache 
{ 
Failed", 
}
۲Ⴕࡹ∗֥ Response Code

View Slide

Pragma: no-cache 
{ 
Failed", 
}
Client ๩Ἶ Basic Auth 
⃾⊈ാḮ≣ೖ≾ἠ header

View Slide

Pragma: no-cache 
{ 
Failed", 
}
ấ↪⁫

View Slide

error = Meaning
invalid_client Client ⃾⊈ാḮ
Authorization Server ⃾҂ԛ Client
ေ߭ 401 Unauthorized
ೂݔ൞Ⴈ Basic Auth ෂԛ Client Auth đ≣ေڸഈ
WWW-Authenticate: Basic

View Slide

error = Meaning
invalid_grant
ิԛ֥ Grant ࠇ൞ Refresh Token ҂ᆞ⃷a
Ἶ௹aФӜ⇍đࠇ Redirection URI ҂ژđ
ࠇ۴Чࣼ҂൞ἡ୆≾ἠ Clientb
൱⃴⊯҂ᆞ⃷

View Slide

error = Meaning
invalid_request
㢻ἡсေṚ⅂aἡਔ҂ᆞ⃷֥Ṛ⅂a 
ᇗ♶ἡṚ⅂aࠇః෰ჰၹẹᇁ↥مࢳồb
unauthorized_client
Client ҂ሙႨ≾⊕ Response Type 
ῲ౼֤ Authorization Codeb
unsupported_grant_type
Authorization Server ҂ᆦჱ൐Ⴈ≾⊕ 
Grant Typeb
invalid_scope
෮ေ౰֥ scope ҂ᆞ⃷a 
҂ૼa↥مࢳồb
Client ᄯӮ֥ấ↪

View Slide

error = Meaning
— —

View Slide

error = Meaning
— —
Q: 㬪൉喁㢻ႵĤ
A: ၹ㬪൞ Client ᆰࢤứ Request ֞ Serverđᆰࢤ₵ 500 ࣼྛ

View Slide

ଦ֞ Token ਔđೂޅյ API
RFC 6750 “Bearer Token Usage”

View Slide

HTTP/1.1 200 OK 
Pragma: no-cache 
{ 
"scopes":"email" 
}

View Slide

Bearer Token
• RFC 6750 ק∕đ၂⊕ OAuth 2.0 ֥ Token
• ႨمቋᾏẪğԛൕ Token ἡ Resource Server
• Token ⤨ಸ⁙⁫ࣼྛ
• Spec ᆺἲקԛൕ Token ֥ٚൔ & ấ↪⇫༏

View Slide

ԛൕ Token ֥ٚم
• (in Header) Authorization: Bearer 2YotnFZF...
• (in Body) &access_token=2YotnFZF...
• (in URL) ?access_token=2YotnFZF... ҂๷ᾑ
ቋ๷ᾑ

View Slide

Authorization: Basic XXXXXXXX
• с⇜ᆦჱ
• ᆰࢤϜ Token ሳԱ٢Ά Header ࣼྛਔ
ቋ๷ᾑ
GET /me.json HTTP/1.1 
Host: api.example.com 
Authorization: Bearer 2YotnFZF...

View Slide

in Request Body
• ℳႨᧄ "Form" ᆭ ֥ request (POST, PATCH etc.)
• ҂ॖၛ൞ multi-part
• Content-Type: application/x-www-form-urlencoded

View Slide

POST /api/articles HTTP/1.1 
Host: api.example.com 
urlencoded 
 
title=Test%20Article 
&content=%28ry%0A%0D 
&access_token=2YotnFZF...

View Slide

҂๷ᾑ
in URL Query Param
• ҂๷ᾑđၹ㬪ॖି὜Фὸᄝ log 䥰
• ေ⃷Ќ response ൞ non-cacheable
• Ⴕ Form ିႨࣼ᾽ਈႨ Form Body

View Slide

GET /api/articles?access_token=2YotnFZF...
HTTP/1.1 
Host: api.example.com
HTTP/1.1 200 OK 
Cache-Control: private (or no-store if not 200)

View Slide

ứളấ↪ℭ֥߭∣ٚൔ

View Slide

Bearer Token Error
1. Ṛ⅂ẖấ
2. Token ҂ᆞ⃷
3. Scope ⃴ཋ҂ቀ

View Slide

߭∣ٚൔ
• ၂ੰႨ WWW-Authenticate header ߭ấ↪
• Ⴕԛൕ Token đҌିڸഈః෰ Error Parameters
• ※ 㢻ἲק҂ିᄜႨ JSON ߭

View Slide

error = Status Meaning
invalid_request 400
㢻ἡсေṚ⅂aἡਔ҂ᆞ⃷֥Ṛ⅂ 
ᇗ♶ἡṚ⅂aᇗ♶ԛൕ Access Token 
ࠇః෰ჰၹẹᇁ↥مࢳồb
invalid_token 401
Access Token Ἶ௹aФӜ߭a↥مࢳồb
Client ॖၛᇗྍണ⃪၂ἠ Token ᄜℷb
insufficient_scope 403
Token ֥ scope ⃴ཋ҂ቀb
Error ॖၛڸഈ scope= ῲิൕ෮ླ⃴ཋb

View Slide

WWW-Authenticate: Bearer realm="The API" 
error="invalid_token" 
error_description="Token is not usable."
HTTP/1.1 403 Forbidden 
WWW-Authenticate: Bearer realm="The API", 
error="insufficient_scope", 
error_description="Scope not sufficient.", 
scope="friend_list photo"

View Slide

ປಆ㢻ԛൕ Access Token
WWW-Authenticate: Bearer realm="The API"
GET /api/articles HTTP/1.1 
Host: api.example.com

View Slide

Token Ἶ௹ → ㍤ứ
Token Refresh

View Slide

Token Refresh
• ଦ Access Token ނứℭ֥ Refresh Token ಀ㍤ứ
• ჰЧ㢻Ⴕứ Refresh Token đࣼ҂ି㍤ứ
• POST ֞ Token Endpoint

View Slide

urlencoded 
 
grant_type=refresh_token 
 
&refresh_token=tGzv3JOkF0XG5Qx2TlKWIA 
 

View Slide

urlencoded 
 
 
 
Token Endpoint

View Slide

urlencoded 
 
 
 
Token Endpoint
іൕw໡ Client ေ㍤ứྍ֥ Tokenx

View Slide

urlencoded 
 
 
 
Token Endpoint
іൕw໡ Client ေ㍤ứྍ֥ Tokenx
scope ॖസ੻đ҂ॖնᧄ 
Access Token ണ⃪Ἶ֥⃴ཋ

View Slide

⚧ᄯ OAuth 2 Provider ֥ٚم

View Slide

= ᄯ Authorization Server

View Slide

Service spec
ཌྷಸ
ᆦჱ֥ Grant Types scope ٳۯ
Refresh
Token
Client ⃾⊈
Facebook ✕ Auth Code, Implicit, Client Cred. comma △ (ሱ⚧) GET
GitHub ✕ Auth Code, Password (ሱ⚧) comma ✕ POST
Twitter ̋ Client Cred. (↥ scope) ✕ Basic
Google ✕ Auth Code, Implicit space ̋ POST
Microsoft ✕ Auth Code, Implicit ĤĤĤ ̋ POST
Dropbox ̋ Auth Code, Implicit (↥ scope) ✕ Basic, POST
Amazon ̋ Auth Code, Implicit space ̋ Basic, POST
Bitly ✕ Auth Code (϶ሱ⚧), Password (↥ scope) ✕
POST (Auth Code),
Basic (Password)
ྍশັѰ ✕ Auth Code comma ✕ Basic, GET
׸ϵ ✕ Auth Code, Implicit comma ̋ POST
BOX ✕ Auth Code (↥ scope) ̋ POST
Basecamp ✕ Auth Code (↥ scope) ̋ POST

View Slide

⦁ದᄸ喁ቓ
• ҂၂קေᆦჱ෮Ⴕ 4 ⊕ Grant Flow
• ҂၂קေႵ Scope
• ҂၂קေႵ Refresh Token

View Slide

⦁ದᄸ喁ቓč҂ݺ֥ٚ૫Ď
✘ ్ Scope ޓ؟ದႨ `,`
✘ Client ⃾⊈҂ᾖ֤׻ᆦჱ HTTP Basic Auth
✘ Bearer Token ҂၂ק൞Ⴈ 
“Bearer” Authorization Header

View Slide

Ⴕ Spec ॖၛ Follow ࣼ Follow
✔ ్ Scope Ⴈॢ۬
✔ Client ⃾⊈ᇀഒေᆦჱ Basic Auth
✔ Bearer Token ࣼႨ 
“Bearer” Authorization Header

View Slide

Step 1: ק∕ Resource Owner

View Slide

Resource Owner
• ࣼק∕Ӯ↌ᅟഈ֥ User ϔ

View Slide

Step 2: ℟ί Client ܵ৘ࢸ૫

View Slide

Client Registration (CRUD)
• id
• secret čℶ㬪ૡ⁫Ď
• Redirect URI
ّᆞ҂൞ἡದὸ֥
෮ၛള⁙⁫ࣼྛ
}
← ေ౰ Developer ൙༵ᆷק

View Slide

Step 3: Ῐ Endpoints

View Slide

• ๙ӈῘᄝᇶᅟđٚьᆰࢤ⃸ User Ⴈ Cookie ֨ೆ
• ⚧ቔ၂ἠ Dialog ⃸ User 㢯קေ҂ေᄍ⇝൱⃴
• User ߭ճᆭᗥđRedirect ߭ Client
• ὜ Redirect ߭ Client đ෮ၛေ༵⃷Ќ Client ᆞ⃷

View Slide

halt if !(client_id and redirect_uri matches)
error(invalid_scope) if !(valid_scope?)
error(unsupported_response_type) 
if !(valid_response_type?)
# other errors (incomplete pseudo code)

View Slide

result = ask_user_for_authorization!
if result == Authorized then 
if response_type == Code 
callback_params = generate_grant_code() 
else if response_type == Token 
callback_params = generate_token()
else if result == Denied then 
callback_params = generate_error_code(access_denied)

View Slide

if response_type == Code 
redirect_to_client_with_query(callback_params)
else if response_type == Token 
redirect_to_client_with_fragment(callback_params)

View Slide

Token Endpoint
• ๙ӈῘᄝ API subdomain
• ᅶ Spec ቓ JSON Response ࣼྛ

View Slide

Token Endpoint
authorize_client! or error(invalid_client)
verify_redirect_uri! or error(invalid_request)
error(invalid_scope) if scope_given and !valid_scope?
# other errors
token = issue_token(expires_in: 30.days)
token_response_by_json(token)

View Slide

Step 4: Ẳ API

View Slide

“Resource Server Guard”
• Ẳᄝ API ቋຓ૫֥wЌಆx(Guard)
• ⇼⊈ૄἠ Request ׻с⇜Ⴕᆞ⃷֥ Token

View Slide

“Resource Server Guard”
fetch_token(from: header, form, query)
error(401) if !(token_given?)
error(400) if !(token_decodable?)
error(invalid_token) if expired? or revoked?
error(insufficient_scope) if scope_sufficient?
yield to API

View Slide

ֻ၂ՑႨ Rails + Grape API
ᆜކ OAuth 2 ࣼഈ൭

View Slide

ֻ၂Ցč੻Ďࣼഈ൭
• Ⴈ Devise ള User (Resource Owner)
• Ⴈ Doorkeeper ἒ Authorization Server
• Ⴈ Grape ἒ API (Resource Server)
• ሱ࠭ख़ Resource Server Guard ῲ⅞ API

View Slide

Why ሱ࠭ख़ Guard
• doorkeeper_for ൞ Rails-Only
• Rack::OAuth2 ປӮ؇ޓۚđ֌с⇜ሱ࠭ᆜކ
• Warden::OAuth2 ۵ Devise वᄝ၂ఏ໡҂὜ࢳ
• Grape::Middleware::Auth::Oauth2 ۴Ч㢻ቓປ
✔ Best Choice

View Slide

Source Available on GitHub
GitHub.com/chitsaou/oauth2-sample-api

View Slide

Step 1: ק∕ Resource Owner

View Slide

ק∕ Resource Owner
$ rails g devise:install # ປ

View Slide

Step 1.5: ᄯ API

View Slide

ᄯ API
class SecretAPI < Grape::API 
namespace "secret" 
format :json 
get "hello" do 
{ 
greeting: "Hi,#{current_user.email}" 
} 
end 
end

View Slide

Step 2: ℟ί Client ܵ৘ࢸ૫

View Slide

Step 3: Ῐ Endpoints

View Slide

Step 2 + 3: 
Ῐ Authorization Server

View Slide

Ῐ Authorization Server
$ gem install doorkeeper 
$ rails g doorkeeper:install 
$ rails g doorkeeper:migration 
$ rake db:migrate

View Slide

℟ק⃾⊈ Resource Owner ֥ٚൔ
# ⃾⊈ Resource Owner ֥ٚمđᆰࢤࢤ Devise 
resource_owner_authenticator do 
current_user || 
warden.authenticate!(:scope => :user) 
end
config/initializers/doorkeeper.rb
※ Ӓܲٚ໓ࡱ

View Slide

New Tables
• oauth_application - Clients Registration
• oauth_access_grant - Stores Auth Grant Codes
• oauth_access_token - 
ᆇᆞނứԛಀ֥ Access Tokensđ 
ЇݣỚ∣֥ Refresh Token č≁℟ἬṅĎ

View Slide

New Routes
Action(s) Path Ⴈ๯
new /oauth/authorize Authorization Endpoint
create /oauth/authorize User ⇝ॖ൱⃴ℭ֥ action
destroy /oauth/authorize User ऋ䌉൱⃴ℭ֥ action
show /oauth/authorize/:code Local ṦℷႨ
update /oauth/authorize Ĥ
create /oauth/token Token Endpoint
show /oauth/token/info Token Debug Endpoint
resources /oauth/applications Clients ܵ৘ࢸ૫ (CRUD)
index /oauth/authorized_applications
User ܵ৘൱⃴Ἶ֥ Clients
destroy /oauth/authorized_applications/:id

View Slide

Doorkeeper Built-In™
✔ Authorization Endpoint & Token Endpoint
✔ Token Debug Endpoint 
čᄝ Implicit Flow ⇼⊈ Token ֥ᆇℯྟĎ
✔ Client Registration Interface (CRUD)
✔ User ܵ৘൱⃴Ἶ֥ Clients ֥ࢸ૫čॖ RevokeĎ

View Slide

Let’s Create a Client
http://localhost:12345/auth/demo/callback

View Slide

Let’s Get an Access Token

View Slide

http://localhost:3000/oauth/authorize?
client_id=4a407c6a8d3c75e17a5560d0d0e4507c77b
047940db6df882c86aaeac2c788d6
&redirect_uri=http://localhost:12345/auth/
demo/callback
&response_type=code

View Slide

(B) Auth. Server ↜ User

View Slide

(C) ൱⃴⊯༯ῲਔ
http://localhost:12345/auth/demo/callback?
code=9e0ad73f94669d9743bb0c2e65c4784f723c11c7
61852477a4d37d0cc9bb914d

View Slide

(D) ଦ Code ㍤ Token

View Slide

Token ֞൭
4ead67fc8917761a7f0cd1f0cae30e905fc93e0d25430
32f58395e5a55b9869e

View Slide

Step 4: Ẳ API
The Most Hard Part

View Slide

api/concerns/api_guard.rb
module APIGuard
extend ActiveSupport::Concern
end

View Slide

Building Resource Server Guard
• Fetch Access Token via Rack::OAuth2
• Find Access Token from Model
• Validate if Token is not Expired && not Revoked
• Validate if Token has Sufficient Scopes
• If All Valid, Pass to Grape API

View Slide

Fetch Access Token via Rack::OAuth2
• use Rack::OAuth2::Server::Resource::Bearer
• ൙ℯഈᆺἌ≡Ϝ yield ԛῲ֥ Token թᄝଖẕ
• ೂݔ Request ҂ầ Token ࣼᆰࢤ Pass ֞༯ἠ stack
• ෮ၛ໡ᆺଦ෱ῲ Fetch Token

View Slide

included do |base| 
# OAuth2 Resource Server Authentication 
use Rack::OAuth2::Server::Resource::Bearer, 
'The API' do |request| 
# Authenticator only fetches the raw token string 
 
# Must yield access token to store it in the env 
request.access_token 
end 
end

View Slide

def get_token_string 
request.env[Rack::OAuth2::Server::Resource:: 
ACCESS_TOKEN] 
end
(in helpers block)

View Slide

Find Access Token Instance
• Doorkeeper::AccessToken.authenticate
• → #find
• returns nil if not found

View Slide

def find_access_token(token_string) 
Doorkeeper::AccessToken.authenticate(token_string) 
end
(in helpers block)

View Slide

Validate the Token
• OAuth2::AccessTokenValidationService.validate
• ᾋҰႵ㢻Ⴕ Expired a Revoked
• ॖၛẖ scopes Ṛ⅂ΆಀᾋҰ scope Ⴕ㢻Ⴕ⃆

View Slide

def validate_access_token(access_token, scopes) 
OAuth2::AccessTokenValidationService 
.validate(access_token, scopes: scopes) 
end
(in helpers block)

View Slide

def validate(token, scopes: []) 
if token.expired? 
return EXPIRED 
 
elsif token.revoked? 
return REVOKED 
 
elsif !self.sufficent_scope?(token, scopes) 
return INSUFFICIENT_SCOPE 
 
else 
return VALID 
end 
end
Token#expired?, Token#revoked? 
൞ Doorkeeper ⤨ࡹ֥

View Slide

def sufficent_scope?(token, scopes) 
if scopes.blank? 
# no scope required => any token is valid 
return true 
else 
# scopes required 
#=> Check sufficiently by Set comparison 
required_scopes = Set.new(scopes) 
authorized_scopes = Set.new(token.scopes) 
 
return authorized_scopes >= required_scopes 
end 
end
≾൞ቋᾏẪ֥ࠢކбᾱ
୆ॖၛ၇ླ౰ℯቔဆෘم

View Slide

ቓ guard! ᄝ Grape 䥰૫Ẳᇾ
get "hello" do 
guard! 
{ 
} 
end 
end

View Slide

def guard!(scopes: []) 
token_string = get_token_string() 
 
if token_string.blank? 
raise MissingTokenError 
 
elsif ( 
access_token = find_access_token(token_string) 
).nil? 
raise TokenNotFoundError
(in helpers block)

View Slide

 
 
elsif ( 
).nil? 
༵ሂԛ Token String
(in helpers block)

View Slide

 
 
elsif ( 
).nil? 
ሂ֥֞൞ॢሳԱđіൕ㢻ἡ Token
(in helpers block)

View Slide

 
 
elsif ( 
).nil? 
ሂ֥֞൞ॢሳԱđіൕ㢻ἡ Token
Ⴕἡ֌ᅳ҂֞đ൞ Invalid Token
(in helpers block)

View Slide

else 
case validate_access_token(access_token, scopes) 
when Oauth2::AccessTokenValidationService 
::INSUFFICIENT_SCOPE 
raise InsufficientScopeError.new(scopes) 
when Oauth2::AccessTokenValidationService::EXPIRED 
raise ExpiredError 
when Oauth2::AccessTokenValidationService::REVOKED 
raise RevokedError 
when Oauth2::AccessTokenValidationService::VALID 
@current_user = User.find(access_token 
.resource_owner_id) 
ennnd

View Slide

else 
ennnd
Scope ҂ژ

View Slide

else 
ennnd
Scope ҂ژ
Ἶ௹ਔ

View Slide

else 
ennnd
Scope ҂ژ
Ἶ௹ਔ
Ӝ⇍ਔ

View Slide

else 
ennnd
Scope ҂ژ
Ἶ௹ਔ
Ӝ⇍ਔ
׻ OK ࣼ℟ current_user

View Slide

ቋᗥ൞ Error Response
• Rack::OAuth2 䥰૫֥ᆰࢤଦῲႨ
• ಌềğinsufficient_scope ҂὜ἡ WWW-Authenticate
• ၹ㬪ᅶ RFC 2617 ᆺႵ 401 ླေ߭≾ἠ Header

View Slide

error_classes = [MissingTokenError, 
TokenNotFoundError, ExpiredError, 
RevokedError, InsufficientScopeError] 
 
rescue_from *error_classes, 
oauth2_bearer_token_error_handler
(in included block)

View Slide

def oauth2_bearer_token_error_handler 
Proc.new {|e| 
response = case e 
when MissingTokenError 
Rack::OAuth2::Server::Resource 
::Bearer::Unauthorized.new 
when TokenNotFoundError 
Rack::OAuth2::Server::Resource 
::Bearer::Unauthorized.new( 
:invalid_token,"Bad Access Token.") 
# etc. etc. 
end 
response.finish 
} 
end (in ClassMethods module)

View Slide

guard_all!
guard_all! 
get "hello" do 
{ 
} 
end 
end

View Slide

module ClassMethods 
def guard_all!(scopes: []) 
before do 
guard! scopes: scopes 
end 
end 
end
(in ClassMethods module)

View Slide

Done

View Slide

$ curl -i http://localhost:3000/api/v1/sample/secret 
WWW-Authenticate: Bearer realm="The API" 
Content-Type: application/json 
Cache-Control: no-cache 
{"error":"unauthorized"}

View Slide

$ curl -i http://localhost:3000/api/v1/sample/secret \ 
> -H "Authorization: Bearer XXXXXXXX" 
WWW-Authenticate: Bearer realm="Protected by OAuth
2.0", error="invalid_token", error_description="Token
is expired. You can either do re-authorization or
token refresh." 
Cache-Control: no-cache 
{"error":"unauthorized"}
č⁙แ TokenĎ

View Slide

$ curl -i http://localhost:3000/api/v1/sample/secret \ 
> -H "Authorization: Bearer
4ead67fc8917761a7f0cd1f0cae30e905fc93e0d2543032f58395e
5a55b9869e" 
HTTP/1.1 200 OK 
 
{"greeting":"Hi, [email protected]"}

View Slide

Final Notes
• Doorkeeper ≁℟㢻Ⴕ⅞Ῐ Client ֥⃴ཋđ୆ὸ֤ေ⅞
• Doorkeeper ҂ିᆷקᆺῘଧུ Flows 
໡Ῐਔ PR ὕ㢻 merge…
• 㢻Ⴕྩ insufficient_scope Error 
ಌ WWW-Authenticate ֥↜ⅳ

View Slide

What about Omniauth?
• github.com/intridea/omniauth-oauth2
• ޓᾏẪđṚ⅂⇔၂⇔ࣼປӮਔ

View Slide

Conclusion
• OAuth 2 Spec ồປҌ὜ᆩ֡෰ᄝἓખ
• ồປ Spec → ෮Ⴕ API ෮Ⴕ Library ୆׻ु֤׭
• ሱ࠭ᆜކ Grape ބ OAuth 2 ఃℯ㢻Ⴕޓₒ 
ᆺေ׭ Spec ࣼ҂ₒ…

View Slide

Final Words
• ၇ಖࡹ∗୆ಀồ specđၹ㬪໡സ੻ޓ؟↱ᾳ
• Ⴍః൞ Security ֥҆ٺ
• Amazon ֥ OAuth 2 Login ໓ࡱ໡ቋ๷ᾑ

View Slide

References
• RFC 6749 (Spec) tools.ietf.org/html/rfc6749
• RFC 6750 (Spec) tools.ietf.org/html/rfc6750
• My Notes: blog.yorkxin.org/tags/OAuth
• Many OAuth2-based API Documents

View Slide

Thank You!
Q&A Time

View Slide

簡單易懂的 OAuth 2.0

簡單易懂的 OAuth 2.0

Yu-Cheng Chuang

More Decks by Yu-Cheng Chuang

Other Decks in Programming

Featured

Transcript