Oauth 2 in Action

by Justin Richer, Antonio Sanso

Oauth 2 in Action OAuth 2 is like the web version of a valet key Instead of unsafe password sharing OAuth offers a much more secure delegation protocol OAuth is used everywhere from large providers like Facebook and Google to small APIs at startups and even cloud services it s the worldwide standard OAuth 2 is the must know security protocol on the web today OAuth 2 in Action teaches practical use and deployment of this protocol from the perspective of a client authorization server and resource serve

Publisher :

Author : Justin Richer, Antonio Sanso

ISBN : 9781617293276

Year : 2016

Language: en

File Size : 9.08 MB

Category : Computers Technology

Justin Richer
Antonio Sanso


OAuth 2 in Action

shelter island

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: [email protected]
©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.
20 Baldwin Road
PO Box 261
Shelter Island, NY 11964

Development editor: Jennifer Stout
Technical development editors: Dennis Sellinger
: David Fombella Pombal
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

brief contents
Part 1  First steps..................................................................1

  What is OAuth 2.0 and why should you care?  3
■  The OAuth dance  21

Part 2 
Building an OAuth 2 environment.......................41


Building a simple OAuth client  43
Building a simple OAuth protected resource  59
Building a simple OAuth authorization server  75
OAuth 2.0 in the real world  93

Part 3 
OAuth 2 implementation
and vulnerabilities............................................. 119


Common client vulnerabilities  121
Common protected resources vulnerabilities  138
Common authorization server vulnerabilities  154
Common OAuth token vulnerabilities  168



brief contents

Part 4 
Taking OAuth further...........................................179


OAuth tokens  181
Dynamic client registration  208
User authentication with OAuth 2.0  236
Protocols and profiles using OAuth 2.0  262
Beyond bearer tokens  282
Summary and conclusions  298

foreword xii
preface xiv
acknowledgments xvii
about this book  xx
about the authors  xxiv
about the cover illustration  xxvi

Part 1  First steps�����������������������������������������������������������������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
Summary 20





  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

Summary 39

Part 2 
Building an OAuth 2 environment������������������������� 41


  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
Summary 58


  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

Summary 74




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
Summary 92


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

Client deployments 109

Web applications  109   Browser applications 110   Native
applications 112    Handling secrets  117

Summary 118

Part 3 
OAuth 2 implementation
and vulnerabilities����������������������������������������������� 119


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
Summary  137




  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

Token replays 151
Summary  153


  Common authorization server vulnerabilities  154
General security 154
Session hijacking 155
9.3 Redirect URI manipulation  157
Client impersonation 162
Open redirector 164
Summary  167


  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


  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



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
Summary 207


  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

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

Summary 235


  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



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

Summary 260


  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

Summary 281


  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
Summary 297



  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


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 protecting resources—most notably APIs. It’s super popular and, apparently, it can do anything. 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 something. 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 antipatterns and using best practices. Stated differently, just because you have the flexibility to do anything and deploy in any way, doesn’t mean that you should.



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.

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 collaboration technologies and how we can get people doing things together using computers. 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 lessons 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


© 2018-2019 uberlabel.com. All rights reserved