API Authorization with OAuth2

Developer Week 2013

Transcript

1. API Authorization with OAuth2 @BastianHofmann
2. show of hands: web application? mobile? desktop? used an oauth api in one of their apps, oauth2? implemented an oauth api themselves? Why is knowing about OAuth important?
3. API because in nearly every web or mobile application you are talking with external apis at some time, be it to get additional data, single-sign-on, imports/exports etc
4. and if you look at the big api providers everybody uses oauth, and a lot of them already oauth2, of course all of them offer their client libraries and sdks which already handle oauth for you, but it's still very important to know how they work and what the security implications are
5. A few words about me before that ...
6. i work at researchgate, the social network for scientists and researchers
7. ResearchGate gives science back to the people who make it happen. We help researchers build reputation and accelerate scientific progress. On their terms. ‟ the goal is to give...
8. over 2.9 million users
9. here some impressions of the page
11. http://gigaom.com/2013/06/05/heres-how-bill-gatess- researchgate-investment-might-change-the-world-for-the- better http://venturevillage.eu/researchgate
12. have this, and also work on some cool stuff
14. in addition to this i also speak frequently on conferences throughout the world
15. work and live in berlin
16. Questions? Ask by the way, if you have any questions throughout this talk, if you don't understand something, just raise your hand and ask. probably my fault anyways since i spoke to quickly or my accent was too bad
17. http://speakerdeck.com/u/bastianhofmann the slides will be available on speakerdeck later on and i will tweet about them
18. http://oauth.net/ So before we start with OAuth2 I want to take a few minutes and quickly explain how the first version of OAuth works, so we understand why OAuth2 is even necessary and why some decisions in OAuth2 were made
19. http://tools.ietf.org/html/rfc5849 you can read up on the spec here
20. lanyrd.com twitter.com Pre Registration of Client at Twitter: - Shared Consumer Key - Shared Consumer Secret first of all the client needs to preregister at the api server, from there it gets a shared consumer key and a shared consumer secret
21. HTTP POST Connect with Twitter lanyrd.com after that each time a user of the client wants to connect with the api
22. twitter.com HTTP POST Connect with Twitter HTTP GET Consumer Key Redirect URI Signature (Consumer Secret) lanyrd.com the client, server to server, with his consumer key and a redirect callback url (more on that one later) requests a request token from the api. this request like all the other server to server requests later is signed with an oauth signature which as the consumer secret as a key. i'll explain oauth signatures later as well.
23. twitter.com HTTP POST Connect with Twitter Request Token Request Token Secret lanyrd.com in response of this request token request the api issues a request token and a request token secret to the client and internally binds them to the consumer key of the client
24. http://twitter.com/authorize? requestToken=... HTTP Redirect lanyrd.com the client also remembers this request token and request token secret, binds them to the current user or his session and redirects the user in the browser to the authorization endpoint of the api, the issued request token is attached as a query parameter to this redirect
25. HTTP GET twitter.com/ authorize the user is is now at the authorization endpoint of the api
26. Login twitter.com/ authorize where he has to log in if he is not logged in already
27. Grant permission twitter.com/ authorize Create verifier and bind it to User and Request Token and after that he grants permission to the client to access the api in his name. if he did that the api provider created a verifier and binds it to the authorizing user and the issued request token
28. Redirect URI? verifier=...&requestToken=.. HTTP Redirect twitter.com/ authorize after that he redirects the user back to the callback url provided by the client in the first step when getting the request token, and adds the authorized request token and the created verifier as query parameters to this redirect
29. HTTP GET lanyrd.com (RedirectURI? verifier=...) the user now gets back to the client
30. HTTP GET HTTP GET Consumer Key, RequestToken Verifier Signature (Consumer & Request Token Secret) twitter.com lanyrd.com which can use the request token, its consumer key and the received verifier to get an access token (server to server) from the api this request is signed with the consumer secret and request token secret as a key
31. HTTP GET Access Token Access Token Secret twitter.com lanyrd.com if everything is valid the api issues an access token and an access token secret which are bound to the client and the authorized user to the client
32. HTTP GET API Request Consumer Key, Access Token Signature (Consumer & Access Token Secret) twitter.com lanyrd.com now finally the client can access the api with its consumer key the access token. each request is signed with a signature that has the consumer secret and the access token secret as a key.
33. POST /oauth/request_token HTTP/1.1 Host: api.twitter.com Authorization: OAuth oauth_consumer_key=“abcdef“, oauth_signature_method=“HMAC-SHA1“, oauth_timestamp=“137131200“, oauth_nonce=“gggg“, oauth_callback=“http%3A%2F %2Fexample.com%2Fcallback“ oauth_signature=“...“ in detail: getting the request token
34. HTTP/1.1 200 OK Content-Type: application/x-www-form- urlencode oauth_token=defghi&oauth_token_secret=jkl mnop&oauth_callback_confirmed=true request token response from the api
35. HTTP/1.1 302 Found Location: https://api.twitter.com/oauth/ authorization?oauth_token=defghi redirect the client's server sends to the user so that the user get's to the api authorization endpoint
36. HTTP/1.1 302 Found Location: http://example.com/callback? oauth_token=defghi&oauth_verifier=qrstuvw redirect from the api authorization endpoint after authorization to to callback url of the client
37. POST /oauth/access_token HTTP/1.1 Host: api.twitter.com Authorization: OAuth oauth_consumer_key=“abcdef“, oauth_token=“defghi“ oauth_signature_method=“HMAC-SHA1“, oauth_timestamp=“137131201“, oauth_nonce=“hhhhh“, oauth_verifier=“qrstuvw“ oauth_signature=“...“ client gets the access token
38. HTTP/1.1 200 OK Content-Type: application/x-www-form- urlencode oauth_token=xzyabc&oauth_token_secret=defg hijk access token response from the api
39. POST /1/statuses/update.json HTTP/1.1 Host: api.twitter.com Authorization: OAuth oauth_consumer_key=“abcdef“, oauth_token=“ xzyabc“ oauth_signature_method=“HMAC-SHA1“, oauth_timestamp=“137131203“, oauth_nonce=“iiiiiii“, oauth_signature=“...“ status=New %20Tweet&trim_user=true&include_entities=tru e finally with the access token the client can access the api for the authorized user
40. Signatures all this request are secured through oauth signatures to prevent man in the middle attacks etc
41. GET /photos/vacation.jpg? oauth_consumer_key=123&oauth_nonce= 456&oauth_signature_method=HMAC- SHA1&oauth_timestamp=1191242096&oau th_token=789&oauth_version=1.0 HTTP/1.1 Host: photos.example.net it's build like this: if you have a request like this, the whole request is normalized
42. GET&http%3A%2F %2Fphotos.example.net%2Fphotos %2Fvacation.jpg&oauth_consumer_key %3D123%26oauth_nonce %3D456%26oauth_signature_method %3DHMAC-SHA1%26oauth_timestamp %3D1191242096%26oauth_token %3D789%26oauth_version%3D1.0 so you have the http method, the url including the sorted query parameters and if there is a request body even a hash over the requestbody, concatenated together this is the so called base string
43. PLAINTEXT and then there are different signature methods where you crypt the signature, of course for testing there is an insecure one: PLAINTEXT, where the basestring is just transported plainly without encryption
44. HMAC-SHA1 Salt: consumerSecret(&tokenSecret) there is HMAC-SHA1 where the basestring is encrypted with the consumer secret and the token secret as a key (shared secret)
45. RSA-SHA1 Public/Private Key or RSA-SHA1 where the key is encrypted/decrypted with a public/private key algorithm
46. Does not work well with non web or JavaScript based clients The „Invalid Signature“ Problem Complicated Flow, many requests Problems but oauth1 has some problems...
47. How to fix it?
48. http://oauth.net/
49. http://www.rfc-editor.org/rfc/rfc6749.txt
50. http://www.rfc-editor.org/rfc/rfc6750.txt
51. Different client profiles No signatures No Token Secrets Cookie-like Bearer Token No Request Tokens Much more flexible regarding extensions Mandatory TSL/SSL What's new?
52. http://hueniverse.com/2012/07/oauth-2-0-and- the-road-to-hell/ ‟It is the biggest professional disappointme nt of my career. Eran Hammer
53. http://www.tbray.org/ongoing/When/201x/ 2012/07/28/Oauth2-dead OAuth 2 is useful today. ‟ Tim Bray
54. Web-Server Profile I‘ll highlight the two most important client profiles for web applications
55. lanyrd.com twitter.com Pre Registration of Client at Twitter: - Shared Client ID - Shared Client Secret - Redirect URI first of all the client needs to preregister at the api server, from there it gets a shared client id and a shared client secret, he also has to preregister a callback url for later use (pre- registration so that we can get rid of the request token step)
56. HTTP(S) POST Connect with Twitter lanyrd.com when the user wants to connect to the api
57. http://twitter.com/authorize? &clientId=... HTTPS Redirect lanyrd.com the client directly redirects him to the authorization endpoint of the api and adds its client id as a query parameter to the url
58. HTTPS GET twitter.com/ authorize the user is is now at the authorization endpoint of the api
59. Login twitter.com/ authorize where he has to log in if he is not logged in already
60. Grant permission twitter.com/ authorize Create authorization code and bind it to User and ClientID and after that he grants permission to the client to access the api in his name. if he did that the api provider creates an authorization code and binds it to the authorizing user and the client's client id
61. Redirect URI?authorizationCode=... HTTPS Redirect twitter.com/ authorize the user is the redirected to the client's pre registered callback url with the generated authorization code as a query parameter
62. HTTPS GET lanyrd.com (RedirectURI? authorizationCo de=...) when this request arrives at the client
63. HTTPS GET HTTPS GET Client ID Authorization Code Client Secret twitter.com lanyrd.com the client can take the authorization code and together with the client id and client secret it can retrieve an access token server to server from the api
64. HTTPS GET Access Token (Refresh Token) twitter.com lanyrd.com if the authorization code is valid the api creates an access token which is bound to the client id and the user authorized by the authorization code and passes it with an optional refresh token to the client
65. HTTPS GET HTTPS API Request Access Token twitter.com lanyrd.com with the access token the client can now access the api
66. HTTPS GET HTTPS GET Client ID Refresh Token Client Secret twitter.com lanyrd.com if the access token expired and the api issued a refresh token the client can use this refresh token and his client id an secret to get a new access token
67. HTTPS GET Access Token Refresh Token twitter.com lanyrd.com
68. HTTPS GET API Request with Access Token twitter.com lanyrd.com
69. HTTP/1.1 302 Found Location: https://api.twitter.com/oauth2/ authorize? response_type=code&client_id=abcdefg&state=x yz&scope=write in detail: the redirect to the authorization server
70. HTTP/1.1 302 Found Location: https://example.com/callback? code=ghijkl&state=xyz redirect back to the preregistered callback url with the authorization code
71. POST /oauth2/token HTTP/1.1 Host: api.twitter.com Content-Type: application/x-www-form- urlencoded;charset=UTF-8 grant_type=authorization_code&code=ghijkl&c lient_id=12345&client_secret=7890 getting the access token
72. POST /oauth2/token HTTP/1.1 Host: api.twitter.com Authorization: Basic mnopqrs Content-Type: application/x-www-form- urlencoded;charset=UTF-8 grant_type=authorization_code&code=ghijkl another way of authorization: header not as parameter in the request body
73. HTTP/1.1 200 OK Content-Type: application/json;charset=UTF-8 { "access_token": "jklmno", "expires_in": 3600, "refresh_token": "qrstuvq", "token_type": "bearer" } access token response
74. GET /1/statuses/home_timeline HTTP/1.1 Host: api.twitter.com Authorization: Bearer jklmno api request
75. Refresh Token
76. POST /oauth2/token HTTP/1.1 Host: api.twitter.com Authorization: Basic mnopqrs Content-Type: application/x-www-form- urlencoded;charset=UTF-8 grant_type=refresh_token&code=qrstuvq getting a new access token with a refresh token
77. Authorization Types oauth2 supports different authorization types
78. Bearer Tokens so far we have seen the bearer token type, which is the most simple one
79. http://www.rfc-editor.org/rfc/rfc6750.txt
80. GET /1/statuses/home_timeline HTTP/1.1 Host: api.twitter.com Authorization: Bearer jklmno you just put the bearer token (the access token) in the authorization header, similar to a cookie, this is secure since everything is done through https
81. https://developers.google.com/ oauthplayground/
82. SSL not possible? what if ...
83. Signatures there is still signature support for oauth2 which is a bit similar to oauth2 but more simple
84. http://tools.ietf.org/html/draft-ietf-oauth-v2-http- mac
85. HTTP/1.1 200 OK Content-Type: application/json;charset=UTF-8 { "access_token“: "jklmno“, "token_type“: "mac“, "expires_in“: 3600, "refresh_token“: "qrstuvq“ "mac_key":"adijq39jdlaska9asud", "mac_algorithm":"hmac-sha-1" } in your access token response you also get a key and algorithm for generating the signature
86. GET /1/statuses/home_timeline HTTP/1.1 Host: api.twitter.com Authorization: MAC id=“jklmno“, nonce=“274312:dj83hs“, mac=“.....“ the builded signature is included in the authorization header together with the access token and a nonce value to prevent replay attacks
87. timestamp\n nonce\n HTTP_METHOD\n HTTP Request URI\n Hostname\n Port\n (Authorization extension) the signatures base string is builded like this and encrypted according to the given algorithm from the access token response
88. And JavaScript?
89. User-Agent Profile for javascript only applications there is the user-agent profile, user-agent because it only happens in the user-agent, the browser
90. http://twitter.com/authorize? &clientId=... Open Popup lanyrd.com when the user wants to connect with an api the javascript application opens a browser popup (or an iframe but popup is better because of fishing) pointing to the authorization endpoint of the api, and adds its client id to it
91. http://twitter.com/authorize? &clientId=... Open Popup lanyrd.com HTTPS GET twitter.co m/ authorize in the popup the user is is now at the authorization endpoint of the api
92. http://twitter.com/authorize? &clientId=... Open Popup lanyrd.com Login twitter.co m/ authorize where he has to log in if he is not logged in already
93. http://twitter.com/authorize? &clientId=... Open Popup lanyrd.com Grant Permission twitter.co m/ authorize if the user grants permission to the api to access the api in his name
94. lanyrd.com HTTPS Redirect RedirectURI#ac cessToken twitter.co m/ authorize RedirectURI #accessTok en lanyrd.com the authorization endpoint generates an access token for the user and the client and redirects the user back to the preregistered callback url of the client. the access token is added to the fragment part of the callback url. this still happens in the popup
95. lanyrd.com RedirectURI #accessTok en Parse Access Token from Fragment Send it to opening window Close popup lanyrd.com because the access token is in the fragment it is not transported to the backend serving the callback url, so the only thing this can do is rendering out a bit of javascript that takes the fragment part of the url and parses the access token out of it and if the callback url is on the same hostname as the javascript app that opened the window, it can make a function call to send the access token to it
96. Same Origin Policy this is secure because of the same origin policy that is built into the browsers. it says that you can only access pages and windows and resources that are on the some host that your application is. this is a very basic security feature in browsers, otherwise malicious sites would have access to everything that is currently open in your browser or where you have session or login cookies stored at
97. lanyrd.com HTTPS Ajax Request to API Access Token twitter.co m now that our javascript application has the access token it can make requests to the api with it
98. Same Origin Policy but remember: same origin policy, we can't just make ajax request to foreign hosts because of this. though for api requests that is a fine and valid use case, since authorization there is not done by cookies.
99. JSONP http://en.wikipedia.org/wiki/JSONP two ways to solve this: one is jsonp
100. Cross Origin Resource Sharing (CORS) or nicer and less hacky ...
101. Backend api.twitter.com Client lanyrd. com AJAX Access-Control-Allow-Origin: * http://www.w3.org/TR/cors/ which works like this: whenever you try to make an ajax request to a foreign hostname, the browser first does a HEAD request to this resource and check if the response contains an 'access-control-allow-origin' header whose value matches the requesting hostname, if it does it executes the request (a bit simplified, there are a couple more headers)
102. GET /oauth2/authorize? response_type=token&client_id=abcdefg&stat e=xyz&scope=write HTTP/1.1 Host: api.twitter.com so useragent flow in detail: this is opening the popup to the authorization endpoint
103. HTTP/1.1 302 Found Location: http://example.com/ callback#access_token=gahorha&state=xyz&exp ires_in=3600&token_type=bearer the redirect back to the preregistered callback url with the access token in the fragment
104. 1.<script> 2. var fragmentString = location.hash.substr(1); 3. var fragment = {}; 4. var fragmentItemStrings = fragmentString.split('&'); 5. for (var i in fragmentItemStrings) { 6. var fragmentItem = fragmentItemStrings[i].split('='); 7. if (fragmentItem.length !== 2) { 8. continue; 9. } 10. fragment[fragmentItem[0]] = fragmentItem[1]; 11. } 12. opener.setAccessToken(fragment['access_token']); 13. window.close(); 14.</script> a bit of code how to get the access token out of the fragment
105. State oauth2 also has some additional features that are very important. most importantly and often overlooked the state query parameter that can and should be added the whole authorization redirects. its very simple if you redirect the user to the authorization endpoint and add a state parameter, you get the same value in the state parameter back when the api redirects the user back to you
106. CSRF this is very important for security and cross site request forgery protection, use it to check that the session where redirect to the authorization endpoint of the api started is the same session as where the redirect back to the client arrived and no attacker got between that and redirected the response with the authorization code or access token to his one session, so that he gets access to the the api data of another user
107. http://homakov.blogspot.co.uk/2012/08/ saferweb-oauth2a-or-lets-just-fix-it.html speaking of security, there are some other potential problems you should be aware of that could arise if you are not careful
108. Scopes Optional parameter for provider specific implementations Additional return values Access Control another one is scopes
109. http://twitter.com/BastianHofmann http://profiles.google.com/bashofmann http://lanyrd.com/people/BastianHofmann http://speakerdeck.com/u/bastianhofmann https://github.com/bashofmann https://www.researchgate.net/profile/Bastian_Hofmann/ mail@bastianhofmann.de thanks, you can contact me on any of these platforms or via mail.