OAuth 2 in Action
Provides pragmatic guidance on what to do ... and what not to do.
OAuth 2 in Action teaches you the practical use and deployment of this HTTP-based protocol from the perspectives of a client, authorization server, and resource server. You'll learn how to confidently and securely build and deploy OAuth on both the client and server sides.
Table of Contents detailed table of contents
Part 1: First steps
1. What is OAuth 2.0 and why should you care?
1.1. What is OAuth 2.0?
1.2. The bad old days: credential sharing (and credential theft)
1.3. Secure delegated access to web APIs
1.3.1. Beyond HTTP Basic and the Password Anti-Pattern
1.3.2. Authorization delegation: why it matters and how it's used
1.3.3. User-driven security and user choice
1.4. OAuth 2.0: the good, the bad and the ugly
1.5. What OAuth isn't
1.6. Summary
2. The OAuth Dance
2.1. Overview of the OAuth 2.0 protocol: getting and using tokens
2.2. Following an OAuth authorization grant in detail
2.3. OAuth's actors: clients, authorization servers, resource owners, and protected resources
2.4. OAuth Components: Tokens, scopes, and authorization grants
2.4.1. Access tokens
2.4.2. Scopes
2.4.3. Refresh tokens
2.4.4. Authorization grants
2.5. Interactions between OAuth's actors and components: back channel, front channel, and endpoints
2.5.1. Back-channel Communication
2.5.2. Front-channel Communication
2.6. Summary
Part 2: Building an OAuth 2.0 Environment
3. Building a Simple OAuth Client
3.1. Register an OAuth client with an authorization server
3.2. Get a token using the authorization code grant type
3.2.1. Sending the authorization request
3.2.2. Processing the authorization response
3.2.3. Adding cross site protection with the state parameter
3.3. Use the token with a protected resource
3.4. Refresh the access token
3.5. Summary
4. Building a Simple Protected Resource
4.1. Parsing the OAuth token from the HTTP request
4.2. Validating the token against our data store
4.3. Serving content based on the token
4.3.1. Different scopes for different requests
4.3.2. Different results for different scopes
4.3.3. Different results for different users
4.3.4. Other access controls
4.4. Summary
5. Building a Simple OAuth Authorization Server
5.1. Managing OAuth client registrations
5.2. Authorizing a client
5.2.1. The Authorization Endpoint
5.2.2. Authorizing the client
5.3. Issuing a token
5.3.1. Authenticating the client
5.3.2. Processing the authorization grant request
5.4. Adding refresh token support
5.5. Adding scope support
5.6. Summary
6. OAuth 2.0 In the Real World
6.1. Authorization Grant Types
6.1.1. Implicit
6.1.2. Client Credentials
6.1.3. Resource Owner Credentials
6.1.4. Assertions
6.1.5. Choosing the Appropriate Grant Type
6.2. Client Deployments
6.2.1. Web Applications
6.2.2. Browser Applications
6.2.3. Native Applications
6.2.4. Handling Secrets
6.3. Summary
Part 3: OAuth 2.0 Implementation Vulnerabilities
7. Common client vulnerabilities
7.1. General client security
7.2. CSRF attack against the client
7.3. Theft of client credentials
7.4. Registration of the redirect uri
7.4.1. Stealing the authorization code through the referrer
7.4.2. Stealing the token through an open redirector
7.5. Theft of authorization codes
7.6. Theft of tokens
7.7. Native applications best practices
7.8. Summary
8. Common Protected Resources Vulnerabilities
8.1. How are protected resources vulnerable?
8.2. Design of a protected resource endpoint
8.2.1. How to protect a resource endpoint
8.2.2. Adding implicit grant support
8.3. Token Replays
8.4. Summary
9. Common authorization server vulnerabilities
9.1. General security
9.2. Session hijacking
9.3. Redirect URI manipulation
9.4. Client impersonation
9.5. Open redirector
9.6. Summary
10. Common OAuth Tokens vulnerabilities
10.1. What is a bearer token?
10.2. Risks and considerations of using bearer tokens
10.3. How to protect bearer tokens
10.3.1. At the client
10.3.2. At the authorization server
10.3.3. At the protected resource
10.4. Authorization code
10.4.1. Proof Key for Code Exchange (PKCE)
10.5. Summary
Part 4: Taking OAuth Further
11. OAuth Tokens
11.1. What are OAuth tokens?
11.2. Structured Tokens: JSON Web Token (JWT)
11.2.1. The Structure of a JWT
11.2.2. JWT Claims
11.2.3. Implementing JWT in our servers
11.3. Cryptographic protection of tokens: JSON Object Signing and Encryption (JOSE)
11.3.1. Symmetric signatures using HS256
11.3.2. Asymmetric signatures using RS256
11.3.3. Other token protection options
11.4. Looking up a token's information online: token introspection
11.4.1. The introspection protocol
11.4.2. Building the introspection endpoint
11.4.3. Introspecting a token
11.4.4. Combining introspection and JWT
11.5. Managing the token lifecycle with token revocation
11.5.1. The token revocation protocol
11.5.2. Implementing the revocation endpoint
11.5.3. Revoking a token
11.6. The OAuth token lifecycle
11.7. Summary
12. Dynamic Client Registration
12.1. How the server knows about the client
12.2. Registering clients at runtime
12.2.1. How the protocol works
12.2.2. Why use dynamic registration?
12.2.3. Implementing the registration endpoint
12.2.4. Having a client register itself
12.3. Client metadata
12.3.1. Table of core client metadata field names
12.3.2. Internationalization of human readable client metadata
12.3.3. Software statements
12.4. Managing dynamically registered clients
12.4.1. How the management protocol works
12.4.2. Implementing the dynamic client registration management API
12.5. Summary
13. User Authentication with OAuth 2.0
13.1. Why OAuth 2.0 is not an authentication protocol
13.1.1. Authentication vs. authorization: a delicious metaphor
13.2. Mapping OAuth to an authentication protocol
13.3. How OAuth 2.0 uses authentication
13.4. Common pitfalls of using OAuth 2.0 for authentication
13.4.1. Access tokens as proof of authentication
13.4.2. Access of a protected API as proof of authentication
13.4.3. Injection of access tokens
13.4.4. Lack of audience restriction
13.4.5. Injection of invalid user information
13.4.6. Different protocols for every potential identity provider
13.5. OpenID Connect: a standard for authentication and identity over OAuth 2.0
13.5.1. ID tokens
13.5.2. The UserInfo endpoint
13.5.3. Dynamic server discovery and client registration
13.5.4. Compatibility with OAuth 2.0
13.5.5. Advanced capabilities
13.6. Building a simple OpenID Connect system
13.6.1. Generating the ID token
13.6.2. Creating the UserInfo endpoint
13.6.3. Parsing the ID token
13.6.4. Fetching the UserInfo
13.7. Summary
14. Protocols and Profiles using OAuth 2.0
14.1. User Managed Access (UMA)
14.1.1. Why UMA matters
14.1.2. How the UMA protocol works
14.2. Health Relationship Trust (HEART)
14.2.1. Why HEART matters to you
14.2.2. The HEART specifications
14.2.3. HEART mechanical profiles
14.2.4. HEART semantic profiles
14.3. International Government Assurance (iGov)
14.3.1. Why iGov matters to you
14.3.2. The future of iGov
14.4. Summary
15. Beyond Bearer Tokens
15.1. Why do we need more than bearer tokens?
15.2. Proof of Possession (PoP) tokens
15.2.1. Requesting and issuing a PoP token
15.2.2. Using a PoP token at a protected resource
15.2.3. Validating a PoP token request
15.3. Implementing PoP token support
15.3.1. Issuing the token and keys
15.3.2. Creating the signed header and sending it to the resource
15.3.3. Parsing the header, introspecting the token, and validating the signature
15.4. TLS token binding
15.5. Summary
Part 5: Finally
16. Summary and conclusions
16.1. The right tool
16.2. Making key decisions
16.3. The wider ecosystem
16.4. The community
16.5. The future
16.6. Summary
Appendixes
Appendix A: An Introduction to Our Code Framework
A.1. An Introduction to Our Code Framework
Appendix B: Extended Code Listings
About the Technology
Think of OAuth 2 as the web version of a valet key. It is an HTTP-based security protocol that allows users of a service to enable applications to use that service on their behalf without handing over full control. And OAuth is used everywhere, from Facebook and Google, to startups and cloud services.
About the book
OAuth 2 in Action teaches you practical use and deployment of OAuth 2 from the perspectives of a client, an authorization server, and a resource server. You'll begin with an overview of OAuth and its components and interactions. Next, you'll get hands-on and build an OAuth client, an authorization server, and a protected resource. Then you'll dig into tokens, dynamic client registration, and more advanced topics. By the end, you'll be able to confidently and securely build and deploy OAuth on both the client and server sides.