Integrating Web Services with OAuth and PHP Matthew Frost Integrating Web Services with OAuth and PHP 1. Dedication 2. Foreword 3. HTTP Basics 1. The Problems with Authentication 2. Breaking Down HTTP Requests/Responses 4. Introduction to OAuth 1. Challenges of Authorization and Authentication 2. Differences Between OAuth 1 and 2 3. When Do I Need a Client/Server 4. Solving Auth Challenges with OAuth 5. Removing the Magic 6. Using Existing Libraries is Good 7. Decoupling Auth 5. OAuth 1 Client 1. Components of an OAuth 1 Signature 2. Understanding Tokens 3. Understanding the Signature 4. Understanding the Nonce 5. Forming a Valid OAuth 1.0 Request 6. OAuth 1 Server 1. Analyzing Request Components 2. Verifying Signatures 3. Distributing Tokens 4. Handling Authentication Failures 5. Handling Authorization Failures 6. Summary 7. OAuth 1 Implementation 1. Existing Libraries 2. Frameworks 3. Service Providers 4. Summary 8. OAuth 2 Client 1. Authorization Flow 2. Scopes 3. Grants 4. Implicit Grant 5. Resource Owner Password Credentials Grant 6. Client Credential Grant 7. Presenting the Access Token 9. OAuth 2 Server 1. SSL/TLS 2. Tokens and Grants 3. Access Control 4. Conclusion 10. OAuth 2 Implementation 1. Existing Libraries 2. Service Providers 3. Conclusion 11. Security 1. Application Security 2. Social Engineering 3. User IDs 4. Token Expiration 5. Conclusion 12. Credits Dedication For everyone who’s helped me along the way, especially Chris Hartjes, Matt Turland, Yitzchok Wilroth, Beth Tucker Long, Tyler Etters, Nick Escobedo, and Jeff Carouth. Foreword “Any sufficiently advanced technology is indistinguishable from magic.” Arthur C. Clarke I became a Facebook user back when it was still exclusive to college students, before it became a platform for third-party applications. Not long after I graduated, I also became an early adopter of Twitter. This was in the days before OAuth, when the API used Basic HTTP authentication and many users would provide their username and password to third parties to try out the latest new app or client. Those were simpler times with a naïve and yet blissful ignorance about them. I still remember using dial-up internet for the first time and being amazed at the possibilities of a world-wide network when I’d only ever seen a few machines wired together to play games over a local area network. The Internet has grown up a great deal since then, and we’ve had to grow with it. Once we got over the excitement of our new found ability to share information and the vast possibilities that lay therein, a critical realization followed: we also needed the ability to protect our information from those who would use it for less than noble purposes. This grew ever more important as applications continued to evolve and increase in complexity, to the point where they would be used to identify us to third parties and share our information with them. At that point, we needed the ability to selectively grant those third parties access to our information without giving up the proverbial keys to the kingdom: our account credentials. All it took was one nefarious or even innocently misbehaving app to wreak havoc with your account. You could reset your password, of course, but that would revoke access to your account for all other apps you used. HTTP authentication was no longer sufficient for the purposes of applications in this situation. A better solution was needed, and Twitter led the charge with OAuth 1 when it became a published standard in 2010. when it became a published standard in 2010. While it paved the way forward for a standard to solve this class of problem, OAuth 1 had its drawbacks. The signature process it used in lieu of SSL was complex and made writing clients cumbersome. It lacked workflows for applications beyond those involving communication between two web applications, such as desktop and mobile. OAuth 2 would succeed it only two years later after the issues with it became apparent. In the midst of all these technological developments, I had the good fortune to become acquainted with Matt Frost through the PHP community and the PHP Mentoring program. We began our relationship as mentor and apprentice, but became friends and even co-workers at one point. I’ve believed for some time that everyone is in a position to be both a student and a teacher to others. Matt has proven that by writing this book and reversing the nature of our original relationship to make me the student, as the book’s subject has been one that I’ve personally struggled with since OAuth first became a standard. I hope you’ll follow me in allowing the words that Matt has written to dispel the magic that may surround OAuth for you as it has for me. While you continue to witness the evolution of the internet and all its technological wonders, I hope you will also be mindful of how it can best benefit humankind. Matthew Turland New Orleans, LA June 24, 2014 HTTP Basics It’s no secret the Internet is everywhere; it powers a large amount of the software we use every single day. An explosion of Application Programming Interfaces (APIs) has significantly increased the number of different services that can be integrated into a single piece of software. In spite of these obvious observations, one thing has remained constant: HTTP (HyperText Transfer Protocol) is the backbone of the Internet. Since the days when browsers were rendering sparkly star backgrounds underneath a myriad of randomly placed images, HTTP has been the protocol responsible for serving up (thankfully, not creating) these web pages. In order to build applications which are responsive and useful for the end user, it’s important to understand HTTP and the structure of the requests, as well as the responses they generate. Though it may seem trivial for static web sites and applications with minimal functionality, in today’s world of highly integrated web applications understanding the protocol is a necessity. An understanding of HTTP allows other systems and developers to interact with our code in a logical way and accelerates the development process. HTTP is a collection of rules for transferring text, images, videos, and sounds in addition to other file and data types across the web via the transmission of requests and responses. Much like linguistic communication, a browser or server will request a specific resource from a web server; the request will also provide specific details to ensure the response can be delivered the way the requesting server expects. The server receiving the request will attempt to act on the specific details of the request and will report back to the requestor whether or not their request could be fulfilled and return any pertinent information regarding the request. That’s a pretty high level overview of how HTTP generally works; if you would like more detail you can read through the HTTP/1.1 RFC 1. This chapter will focus on the very basics of HTTP. It is not intended to be an exhaustive resource on the topic, but should provide enough information to gain a better understanding of how OAuth works in the context of an application. The Problems with Authentication We all interact with authentication and authorization on a daily basis. In fact, most of the time it has nothing to do with the code you write or the applications you use. If you have a keypad on your garage, a swipe card to enter the office, or a debit card with a Personal Identification Number (PIN) then you are constantly authorizing transactions and actions. We are also aware of the risks and precautions we need to take to ensure that information isn’t disseminated. Losing your swipe card, debit card, or PIN can lead to unauthorized users gaining access to your finances or place of employment. Your garage code can lead to your house being vandalized, burgled, or worse. We treat these scenarios as serious security breaches, as we should. If we’re smart, our PIN isn’t the same as our garage code and doesn’t contain any other personal information that can be used to gain access to other systems. We have the same risks and should be taking equally effective precautions with interacting with applications on the internet. As more of our daily lives have moved online we appreciate the convenience, but don’t always consider the legitimate security risks (or the impact) breaches can have on our professional and personal lives. What it comes to down to is being as certain as possible that when our online accounts, application accounts and residential security systems authorize access, we’re the person initiating those requests. Imagine the outrage if your bank made your PIN available through relatively little effort. As application developers, we need to take great care to ensure the authorizing information our users trust us with is effectively protected. Most applications these days require you to login with a user name and password. It’s more common than not for users to have accounts on multiple web sites providing a myriad of different services. Some applications have leveraged this fact and allow you to login with credentials from popular services like Facebook, Twitter, and GitHub–to name a few. While this is usually quite convenient, it should make us wonder “Am I giving my Facebook credentials to another website?” By now we know this isn’t the case. We see this when we are redirected to the Facebook or Twitter login page to enter our credentials and we understand the results of our authentication attempts are then communicated back to the application we are trying to use. Without this service to handle the interactions application we are trying to use. Without this service to handle the interactions between services, it becomes very insecure for two applications to interact with each other. It’s important to understand this point because it helps to understand the role OAuth fills in our modern day web fueled world. One of the largest fears is that somehow our credentials will be sent across the internet in plain-text. Plain-text information is easily captured by hackers; if our personal password practices are sloppy, this can open anyone up to a world of professional, financial, and even personal pain. You might be wondering who would pass plain-text credentials across the internet in an unencrypted manner. All it takes is one application getting sloppy with your personal information and the havoc mentioned above is right around the corner. As responsible web developers, we rely on HTTP requests to deliver enough information in the request to properly identify a user (authentication) and allow the application to determine whether the user has access to the requested resource (authorization). When you break it down, developers are responsible for so many difficult things end users take for granted. There is an expectation that other users will not be able to make requests on their behalf, that their user name and password will be properly protected, and that they will be able access everything they have permission to access. No matter your experience level, these are difficult problems and require a great deal of thought and planning to address.