OAuth 2 in Action (Justin Richer, Antonio Sanso) (Z-Library)

📄 File Format: PDF

💾 File Size: 14.1 MB

📖 Read Online ⬇️ Download

Registered users can read the full content for free

Register as a Gaohf Library member to read the complete e-book online for free and enjoy a better reading experience.

📄 Page 1

M A N N I N G Justin Richer Antonio Sanso FOREWORD BY Ian Glazer

📄 Page 2

OAuth 2 in Action JUSTIN RICHER ANTONIO SANSO M A N N I N G shelter island

📄 Page 3

For online information and ordering of this and other Manning books, please visit www.manning.com. The publisher offers discounts on this book when ordered in quantity. For more information, please contact Special Sales Department Manning Publications Co. 20 Baldwin Road PO Box 261 Shelter Island, NY 11964 Email: orders@manning.com ©2017 by Manning Publications Co. All rights reserved. No part of this publication may be reproduced, stored in a retrieval system, or transmitted, in any form or by means electronic, mechanical, photocopying, or otherwise, without prior written permission of the publisher. Many of the designations used by manufacturers and sellers to distinguish their products are claimed as trademarks. Where those designations appear in the book, and Manning Publications was aware of a trademark claim, the designations have been printed in initial caps or all caps. Recognizing the importance of preserving what has been written, it is Manning’s policy to have the books we publish printed on acid-free paper, and we exert our best efforts to that end. Recognizing also our responsibility to conserve the resources of our planet, Manning books are printed on paper that is at least 15 percent recycled and processed without the use of elemental chlorine. Manning Publications Co. Development editor: Jennifer Stout 20 Baldwin Road Technical development editors: Dennis Sellinger PO Box 261 : David Fombella Pombal Shelter Island, NY 11964 Copyeditor: Progressive Publishing Services Technical proofreader: Ivan Kirkpatrick Composition: Progressive Publishing Services Cover design: Marija Tudor ISBN: 9781617293276 Printed in the United States of America 1 2 3 4 5 6 7 8 9 10 -- EBM -- 22 21 20 19 18 17 ∞

📄 Page 4

iii brief contents Part 1 First steps .................................................................1 1 ■ What is OAuth 2.0 and why should you care? 3 2 ■ The OAuth dance 21 Part 2 Building an OAuth 2 environment ......................41 3 ■ Building a simple OAuth client 43 4 ■ Building a simple OAuth protected resource 59 5 ■ Building a simple OAuth authorization server 75 6 ■ OAuth 2.0 in the real world 93 Part 3 OAuth 2 implementation and vulnerabilities ............................................119 7 ■ Common client vulnerabilities 121 8 ■ Common protected resources vulnerabilities 138 9 ■ Common authorization server vulnerabilities 154 10 ■ Common OAuth token vulnerabilities 168

📄 Page 5

iv brief contents Part 4 Taking OAuth further ..........................................179 11 ■ OAuth tokens 181 12 ■ Dynamic client registration 208 13 ■ User authentication with OAuth 2.0 236 14 ■ Protocols and profiles using OAuth 2.0 262 15 ■ Beyond bearer tokens 282 16 ■ Summary and conclusions 298

📄 Page 6

v contents foreword xii preface xiv acknowledgments xvii about this book xx about the authors xxiv about the cover illustration xxvi Part 1 First steps .................................................................1 1 What is OAuth 2.0 and why should you care? 3 1.1 What is OAuth 2.0? 3 1.2 The bad old days: credential sharing (and credential theft) 7 1.3 Delegating access 11 Beyond HTTP Basic and the password-sharing antipattern 13 Authorization delegation: why it matters and how it’s used 14 User-driven security and user choice 15 1.4 OAuth 2.0: the good, the bad, and the ugly 16 1.5 What OAuth 2.0 isn’t 18 1.6 Summary 20

📄 Page 7

vi contents 2 The OAuth dance 21 2.1 Overview of the OAuth 2.0 protocol: getting and using tokens 21 2.2 Following an OAuth 2.0 authorization grant in detail 22 2.3 OAuth’s actors: clients, authorization servers, resource owners, and protected resources 31 2.4 OAuth’s components: tokens, scopes, and authorization grants 32 Access tokens 32 ■ Scopes 32 ■ Refresh tokens 33 ■ Authorization grants 34 2.5 Interactions between OAuth’s actors and components: back channel, front channel, and endpoints 35 Back-channel communication 35 ■ Front-channel communication 36 2.6 Summary 39 Part 2 Building an OAuth 2 environment .........................41 3 Building a simple OAuth client 43 3.1 Register an OAuth client with an authorization server 44 3.2 Get a token using the authorization code grant type 46 Sending the authorization request 47 ■ Processing the authorization response 49 ■ Adding cross-site protection with the state parameter 51 3.3 Use the token with a protected resource 51 3.4 Refresh the access token 54 3.5 Summary 58 4 Building a simple OAuth protected resource 59 4.1 Parsing the OAuth token from the HTTP request 60 4.2 Validating the token against our data store 62 4.3 Serving content based on the token 65 Different scopes for different actions 66 ■ Different scopes for different data results 68 ■ Different users for different data results 70 ■ Additional access controls 73 4.4 Summary 74

📄 Page 8

contents vii 5 Building a simple OAuth authorization server 75 5.1 Managing OAuth client registrations 76 5.2 Authorizing a client 77 The authorization endpoint 78 ■ Authorizing the client 79 5.3 Issuing a token 82 Authenticating the client 83 ■ Processing the authorization grant request 84 5.4 Adding refresh token support 86 5.5 Adding scope support 88 5.6 Summary 92 6 OAuth 2.0 in the real world 93 6.1 Authorization grant types 93 Implicit grant type 94 ■ Client credentials grant type 97 ■ Resource owner credentials grant type 101 ■ Assertion grant types 106 ■ Choosing the appropriate grant type 108 6.2 Client deployments 109 Web applications 109 ■ Browser applications 110 ■ Native applications 112 ■ Handling secrets 117 6.3 Summary 118 Part 3 OAuth 2 implementation and vulnerabilities ............................................... 119 7 Common client vulnerabilities 121 7.1 General client security 121 7.2 CSRF attack against the client 122 7.3 Theft of client credentials 125 7.4 Registration of the redirect URI 127 Stealing the authorization code through the referrer 128 ■ Stealing the token through an open redirector 132 7.5 Theft of authorization codes 134 7.6 Theft of tokens 134 7.7 Native applications best practices 136 7.8 Summary 137

📄 Page 9

viii contents 8 Common protected resources vulnerabilities 138 8.1 How are protected resources vulnerable? 138 8.2 Design of a protected resource endpoint 139 How to protect a resource endpoint 140 ■ Adding implicit grant support 148 8.3 Token replays 151 8.4 Summary 153 9 Common authorization server vulnerabilities 154 9.1 General security 154 9.2 Session hijacking 155 9.3 Redirect URI manipulation 157 9.4 Client impersonation 162 9.5 Open redirector 164 9.6 Summary 167 10 Common OAuth token vulnerabilities 168 10.1 What is a bearer token? 168 10.2 Risks and considerations of using bearer tokens 170 10.3 How to protect bearer tokens 170 At the client 171 ■ At the authorization server 172 ■ At the protected resource 173 10.4 Authorization code 173 Proof Key for Code Exchange (PKCE) 174 10.5 Summary 178 Part 4 Taking OAuth further .......................................... 179 11 OAuth tokens 181 11.1 What are OAuth tokens? 181 11.2 Structured tokens: JSON Web Token ( JWT) 183 The structure of a JWT 183 ■ JWT claims 185 ■ Implementing JWT in our servers 186

📄 Page 10

contents ix 11.3 Cryptographic protection of tokens: JSON Object Signing and Encryption ( JOSE) 188 Symmetric signatures using HS256 189 ■ Asymmetric signatures using RS256 191 ■ Other token protection options 195 11.4 Looking up a token’s information online: token introspection 196 The introspection protocol 196 ■ Building the introspection endpoint 198 Introspecting a token 200 ■ Combining introspection and JWT 201 11.5 Managing the token lifecycle with token revocation 202 The token revocation protocol 202 ■ Implementing the revocation endpoint 203 ■ Revoking a token 204 11.6 The OAuth token lifecycle 207 11.7 Summary 207 12 Dynamic client registration 208 12.1 How the server knows about the client 209 12.2 Registering clients at runtime 210 How the protocol works 210 ■ Why use dynamic registration? 212 Implementing the registration endpoint 214 ■ Having a client register itself 217 12.3 Client metadata 219 Table of core client metadata field names 220 ■ Internationalization of human-readable client metadata 220 ■ Software statements 223 12.4 Managing dynamically registered clients 225 How the management protocol works 225 ■ Implementing the dynamic client registration management API 228 12.5 Summary 235 13 User authentication with OAuth 2.0 236 13.1 Why OAuth 2.0 is not an authentication protocol 237 Authentication vs. authorization: a delicious metaphor 237 13.2 Mapping OAuth to an authentication protocol 238 13.3 How OAuth 2.0 uses authentication 241

📄 Page 11

x contents 13.4 Common pitfalls of using OAuth 2.0 for authentication 242 Access tokens as proof of authentication 242 ■ Access of a protected API as proof of authentication 243 ■ Injection of access tokens 244 ■ Lack of audience restriction 244 ■ Injection of invalid user information 245 ■ Different protocols for every potential identity provider 245 13.5 OpenID Connect: a standard for authentication and identity on top of OAuth 2.0 246 ID tokens 246 ■ The UserInfo endpoint 248 ■ Dynamic server discovery and client registration 250 ■ Compatibility with OAuth 2.0 252 ■ Advanced capabilities 252 13.6 Building a simple OpenID Connect system 253 Generating the ID token 254 ■ Creating the UserInfo endpoint 255 ■ Parsing the ID token 257 ■ Fetching the UserInfo 259 13.7 Summary 260 14 Protocols and profiles using OAuth 2.0 262 14.1 User Managed Access (UMA) 263 Why UMA matters 263 ■ How the UMA protocol works 265 14.2 Health Relationship Trust (HEART) 277 Why HEART matters to you 277 ■ The HEART specifications 278 HEART mechanical profiles 278 ■ HEART semantic profiles 280 14.3 International Government Assurance (iGov) 280 Why iGov matters to you 280 ■ The future of iGov 281 14.4 Summary 281 15 Beyond bearer tokens 282 15.1 Why do we need more than bearer tokens? 283 15.2 Proof of Possession (PoP) tokens 283 Requesting and issuing a PoP token 284 ■ Using a PoP token at a protected resource 287 ■ Validating a PoP token request 288 15.3 Implementing PoP token support 289 Issuing the token and keys 289 ■ Creating the signed header and sending it to the resource 291 ■ Parsing the header, introspecting the token, and validating the signature 292 15.4 TLS token binding 294 15.5 Summary 297

📄 Page 12

contents xi 16 Summary and conclusions 298 16.1 The right tool 298 16.2 Making key decisions 299 16.3 The wider ecosystem 301 16.4 The community 302 16.5 The future 303 16.6 Summary 303 appendix A An introduction to our code framework 305 appendix B Extended code listings 311 index 327

📄 Page 13

xii foreword There is nothing more daunting than a blank page. It stares at you. It taunts you. It’s not like you don’t know what you want to do. You have a clear picture of the awesome that you want to unleash. You can almost envision the smiles on your boss’s or customer’s face as they delight in the awesome you will create. But the problem is there’s a blank page in front of you. So you reach for your tools. Because you’re reading this, it’s likely you are a developer or identity management professional. Either way, you know that security is paramount and you want to protect the awesome that you intend to build. Enter OAuth. You’ve heard of it. You know it has something to do with protect- ing resources—most notably APIs. It’s super popular and, apparently, it can do any- thing. And the problem with things that can do anything is that they make it hard to do something. They are yet another blank page. Enter Justin and Antonio and this book. The easiest way to get over the paralysis when working with a thing that can do anything is to start and just try to do some- thing. This book not only explains what OAuth does, it gently guides you through the process of doing something, at the end of which not only will you have a very solid understanding of OAuth as a tool, but you’ll no longer have a blank page in front of you—you’ll be ready to deliver the awesome that’s in your head. OAuth is a very powerful tool. Its power comes from its flexibility. Flexibility often means the ability to not only do what you want to do, but also the ability to do things in an unsafe way. Because OAuth governs access to APIs, which in turn gates access to your important data, it’s crucial that you do use it in a safe way by avoiding anti- patterns and using best practices. Stated differently, just because you have the flex- ibility to do anything and deploy in any way, doesn’t mean that you should.

📄 Page 14

foreword xiii There’s another thing about OAuth we might as well get on the table—you are not working with OAuth because you want to work with OAuth. You are working with OAuth because you want to do something else—most likely orchestrate a bunch of API calls and then do something awesome with the results. You’re thinking about a full page; you’re thinking about the awesome you want to unleash. OAuth is a way to get there, and to get there more securely. Thankfully, Justin and Antonio provide pragmatic guidance on what to do and what not to do. They acknowledge both the “I just want to get this done” and the “I want to make sure this is secure” mindsets you have. With the page filled, with the awesome out of your head and in your customers’ hands, you realize the job wasn’t so hard after all. —IAN GLAZER SENIOR DIRECTOR, IDENTITY SALESFORCE

📄 Page 15

xiv preface My name is Justin Richer, and I’m not a classically trained security nerd, even though I pretend to be one for my day job as a consultant. My background is in collabora- tion technologies and how we can get people doing things together using comput- ers. Even so, I’ve been working with OAuth for a long time, having implemented several early OAuth 1.0 servers and clients to connect the collaboration systems that I was conducting research with at the time. It was around then that I came to appreciate that you needed to have a good, implementable, usable security system if your application architecture was going to survive in the real world. Around this time, I attended the early Internet Identity Workshop meetings, where people were talking about a next generation of OAuth, something that would build on the les- sons learned from using OAuth 1.0 out in the real world. When the development of OAuth 2.0 started up in the Internet Engineering Task Force (IETF), I joined the group and dove face first into the debates. Several years later, we came up with a specification. It wasn’t perfect, but it worked pretty well, people got it, and it caught fire. I stayed involved with the OAuth Working Group, and even served as editor for the Dynamic Registration (RFC 7591 and 7592) and Token Introspection (RFC 7662) extensions to OAuth. Today, I’m the editor or author for parts of the OAuth Proof of Possession (PoP) suite, as well as the technical editor for several profiles and extensions of OAuth and its related protocols. I worked on the OpenID Connect core specification, and my team and I implemented a fairly well-received OAuth and OpenID Connect server and client suite, MITREid Connect. I suddenly found myself talking about OAuth 2.0 to many different audiences and implementing it

📄 Page 16

preface xv on a wide variety of systems. I’d taught classes, given lectures, and written a handful of articles about the subject. So when Antonio Sanso, a well-respected security researcher in his own right, approached me to write this book together, it made sense for me to jump in. We looked around at what books were available on OAuth 2.0, and were unimpressed. Most of the material we found was specific to a service: How to write an OAuth client to talk to Facebook or Google, for instance. Or How to authorize your native application to GitHub’s API. And if that’s all you care about, there’s plenty of material out there. But what we didn’t see was something that would take the reader through the entire OAuth system, explain- ing why it is designed the way that it is, pointing out its flaws and limitations as well as its strengths. We decided that there was a need for a more comprehensive approach, and we decided to make it the best that we could. Consequently, this book doesn’t talk to any specific real-world OAuth provider, nor does it get into detail on a particular API or vertical domain. Instead, this book focuses on doing OAuth for its own sake, so that you can see how all the gears mesh together when you turn the cranks. We built out a code framework that, we hoped, would allow readers to focus on the core aspects of OAuth without getting overly caught up in the implementation plat- form details. After all, we didn’t want a book that was “How to implement OAuth 2.0 on Platform Du Jour,” but rather, “How the nuts and bolts of OAuth 2.0 work so you can use whatever platform you want.” So we went with a relatively simple Node.js framework, built on Express.js, and liberally used library code to abstract away the platform-specific weirdness as much as possible. Still, it’s JavaScript, so some of that weirdness crept in from time to time, as it would on any platform. But it’s our hope that you will be able to apply the methods and themes used here to your chosen language, platform, and architecture. Speaking of histories, how did we even get here? The story starts in 2006, when several web service companies, including Twitter and Ma.Gnolia, had complementary applications and wanted their users to be able to connect them together. At the time, this type of connection was typically accomplished by asking the user for their creden- tials on the remote system and sending those credentials to the API. However, the web- sites in question used a distributed identity technology, OpenID, to facilitate login. As a consequence, there were no usernames or passwords that could be used for the API. To overcome this, the developers sought to create a protocol that would allow their users to delegate access to the API. They based their new protocol on several propri- etary implementations of this same concept, including Google’s AuthSub and Yahoo!’s BBAuth. In all of these, a client application is authorized by a user and receives a token that can then be used to access a remote API. These tokens were all issued with a public and private portion, and this protocol used a novel (if in retrospect fragile) crypto- graphic signing mechanism so that it could be used over non-TLS HTTP connections. They called their protocol OAuth 1.0 and published it as an open standard on the web.

📄 Page 17

xvi preface It quickly gained traction, and free implementations in several languages were made available alongside the specification itself. It worked so well and developers liked it so much that even the large internet companies soon deprecated their own proprietary mechanisms that had inspired OAuth in the first place. As happens with many new security protocols, a flaw was found early on in OAuth 1.0’s life, leading to the development of OAuth 1.0a to close a session fixation vulner- ability. This version was later codified in the IETF as RFC 5849. At this point, a commu- nity was beginning to grow around the OAuth protocol, and new use cases were being developed and implemented. Some of these pushed OAuth into places that it was never meant to be used in, but these off-label OAuth uses worked better than any avail- able alternatives. Still, OAuth 1.0 was a monolithic protocol designed to provide one mechanism to solve all use cases, and it was venturing into uncomfortable territory. Soon after the publication of RFC 5849, the Web Resource Access Protocol (WRAP) was published. This proposed protocol took the core aspects of the OAuth 1.0a pro- tocol—a client, delegation, and tokens—and expanded them to be used in different ways. WRAP did away with many of OAuth 1.0’s more confusing and problem-prone aspects, such as its custom signature calculation mechanism. After much debate in the community, WRAP was decided on as the basis for the new OAuth 2.0 protocol. Where OAuth 1.0 was monolithic, OAuth 2.0 was modular. The modularity in OAuth 2.0 allowed it to be a framework that could be deployed and used in all of the ways that OAuth 1.0 had been in practice, but without twisting core aspects of the protocol. OAuth 2.0 essentially provided recipes. In 2012, the core OAuth 2.0 specifications were ratified by the IETF, but the com- munity was far from done with it. This modularity was further codified by splitting the specification into two complementary pieces: RFC 6749 details how to get a token, while RFC 6750 details how to use a particular type of token (the Bearer token) at a protected resource. Furthermore, the core of RFC6749 details multiple ways to get a token and provides an extension mechanism. Instead of defining one complex method to fit different deployment models, OAuth 2.0 defines four different grant types, each suited to a different application type. Today, OAuth 2.0 is the premier authorization protocol in use on the web. It’s used by everything: from large internet companies to small startups, to enterprises, to just about everything in between and beyond. A whole ecosystem of extensions, profiles, and entire protocols built on top of OAuth 2.0 has sprung up, with people finding new and interesting ways to use this foundational technology. It’s our goal that this book will help you understand not only what OAuth 2.0 is and why it works the way it does, but how you can best use it to solve your own problems and build your own systems. JUSTIN RICHER

📄 Page 18

xvii acknowledgments Creating this book has been quite the journey. Ever since we embarked on the proj- ect and started putting the outline together, we had a feeling it was going to take a lot more sweat than we could have ever been prepared for. We were more right than we realized at the time, and it’s with great pleasure that we are finally able to write this part, thanking the many people who helped make it happen. We can’t possibly name you all here, so accept our humble thanks even if your name isn’t listed here explicitly. First off, this book would have never happened without the input and encourage- ment of the OAuth Working Group in the IETF and the larger OAuth and open standards communities. In particular, John Bradley and Hannes Tschofenig each provided invaluable input to the text at various points. Ian Glazer, William Dennis, Brian Campbell, Dick Hardt, Eve Maler, Mike Jones, and many others in the com- munity encouraged us to create the book and helped provide important informa- tion to the internet. Aaron Parecki provided us space on oauth.net to not only talk about the book but also publish topical articles, including an early form of what became chapter 13. And special thanks to Ian for contributing the foreword and endorsing our work. This book would literally not exist without the help and input from the team from Manning Publications. Our fantastic team of editors and support staff included Michael Stephens, Erin Twohey, Nicole Butterfield, Candace Gillhoolley, Karen Miller, Rebecca Rinehart, Ana Romac, and especially our amazing editor Jennifer Stout. Thanks to Ivan Kirkpatrick, Dennis Sellinger, and David Fombella Pombal for making sure the technical bits made sense. A big thanks to everyone who took a

📄 Page 19

xviii acknowledgments chance and preordered the book as a MEAP; the early feedback we got from you was vital in making this the best book we could make it. We would also like to thank our peer reviewers who read the manuscript at various stages of its development and provided invaluable feedback along the way: Alessandro Campeis, Darko Bozhinovski, Gianluigi Spagnuolo, Gregor Zurowski, John Guthrie, Jorge Bo, Richard Meinsen, Thomas O’Rourke, and Travis Nelson. Justin Richer Incomparable thanks are due to my coauthor, Antonio Sanso. His security and crypto- graphic expertise far outstrips anything I could dream of achieving, and it’s been an honor to work with him. Starting the book was his idea in the first place, and the whole project has been a collaborative effort. Thanks to my friends Mark Sherman and Dave Shepherd, both of whom success- fully published tech books before I first set words to the page. Their existence served to remind me that there was a light at the end of the tunnel, and their experience in navigating the publishing world was a great help. Thanks to John Brooks, Tristan Lewis, and Steve Moore, whom I was able to bounce ideas and phrases off of, even if they didn’t always realize I was doing it at the time. Many thanks to my clients over the last year for putting up with me disappearing at random times to go off and write. Thanks are especially due to Debbie Bucci and Paul Grassi, as their fantastic work programs have helped give me the direct experience needed to ground this book in the real world. I can’t possibly express enough thanks to my friend and colleague, Sarah Squire. She originally turned me on to the Node.js frameworks used in the exercises throughout the book, and I believe that, thanks to a trip to an office store, she has the distinction of owning the first printed version of this book. Overall, her encouragement, support, critique, and enthusiasm for this project has been without compare, and I doubt that the book would have really happened without her. Finally, but perhaps most importantly, a sincere and deep thank you to my entire family. The patience of my wife, Debbie, and my kids, Lucien, Genevieve, and Xavier, has been incredible. Between late nights and seemingly endless weekends with me locked up in my office, just out of reach, I’m sure they started to wonder if I’d ever come out, but now I’m glad to say there should be a whole lot more time to play Legos. Antonio Sanso Working on this book has been quite a ride, and it’s with great delight and satisfaction that I write this part. In the end, as with everything, it’s the journey and not the destina- tion that matters. My contribution to this book could not be possible without the help of many people surrounding me. I would like to thank my employer, Adobe Systems, and my managers Michael Marth and Philipp Suter for giving me the green light to work on this book.

📄 Page 20

acknowledgments xix OAuth is a widespread protocol written in a collaborative way by many people under the IETF umbrella. Some of those people are the brightest minds in the security com- munity. We had the privilege to have some extremely useful comments on the work-in- progress draft by John Bradley, Hannes Tschofenig and William Denniss. It is incredible how friendship can have an influence on someone’s life. For this reason, I’d like to thank, in no particular order: Elia Florio for being a constant source of inspiration; Damien Antipa for being so patient while explaining the most arcane part of Javascript and CSS; Francesco Mari, who introduced me to the beautiful world of Node.js and tirelessly listened my endless complains; Joel Richard for helping me with the magic of Apache Cordova; Alexis Tessier, the most talented designer I ever met; and Ian Boston for proofreading. And last but not least, Justin Richer, who has been the best coauthor I could ever hope for. You rock, Justin! But I can’t finish without a special thank you to the people I love. To my parents. They always encouraged me to pursue studying, without putting any pressure on me, even if they didn’t study themselves. Their support was unique. To my brother and sister who also encouraged me, especially in the early stage of my university time. And of course, the biggest thank you goes to my fiancée (soon wife) Yolanda, who supports and continuously encourages me on everything I do. Finally, to Santiago, my son, who helps me remember every single day how beautiful life is. I love you.