CORS in Action: Creating and consuming cross-origin APIs

By Monsur Hossain

Summary

CORS in Action introduces Cross-Origin Resource Sharing (CORS) from both the server and the client perspective. It starts with the basics: how to make CORS requests and how to implement CORS on the server. It then explores key details such as performance, debugging, and security. API authors will learn how CORS opens their APIs to a wider range of users. JavaScript developers will find valuable techniques for building rich web apps that can take advantage of APIs hosted anywhere. The techniques described in this book are especially applicable to mobile environments, where browsers are guaranteed to support CORS.

Purchase of the print book includes a free eBook in PDF, Kindle, and ePub formats from Manning Publications.

About the Book

Suppose you need to share some JSON data with another application or service. If everything is hosted on one domain, it's a snap. But if the data is on another domain, the browser's "same-origin" policy stops you cold. CORS is a new web standard that enables safe cross-domain access without complex server-side code. Mastering CORS makes it possible for web and mobile applications to share data simply and securely.

CORS in Action introduces CORS from both the server and the client perspective. It starts with making and enabling CORS requests and then explores performance, debugging, and security. You'll learn to build apps that can take advantage of APIs hosted anywhere and how to write APIs that expand your products to a wider range of users.

For web developers comfortable with JavaScript. No experience with CORS is assumed.

What's Inside

• CORS from the ground up
• Serving and consuming cross-domain data
• Best practices for building CORS APIs
• When to use CORS alternatives like JSON-P and proxies

About the Author

Monsur Hossain is an engineer at Google who has worked on API-related projects such as the Google JavaScript Client, the APIs Discovery Service, and CORS support for Google APIs.

Table of Contents

PART 1 INTRODUCING CORS
1. The Core of CORS
2. Making CORS requests
PART 2 CORS ON THE SERVER
3. Handling CORS requests
4. Handling preflight requests
5. Cookies and response headers
6. Best practices
PART 3 DEBUGGING CORS REQUESTS
7. Debugging CORS requests

APPENDIXES

1. CORS reference
2. Configuring your environment
3. What is CSRF?
4. Other cross-origin techniques

• Language: English
• Publisher: Manning
• Release date: Oct 20, 2014
• ISBN: 9781638353256

Monsur Hossain

Monsur Hossain is an engineer at Google who has worked on API-related projects such as the Google JavaScript Client, the APIs Discovery Service, and CORS support for Google APIs.

Book preview

Copyright

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 761

        Shelter Island, NY 11964

        Email: 

[e-mail]

©2015 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.

ISBN: 9781617291821

Printed in the United States of America

1 2 3 4 5 6 7 8 9 10 – EBM – 19 18 17 16 15 14

Dedication

For Haroun and Annisa

Brief Table of Contents

Copyright

Brief Table of Contents

Table of Contents

Foreword

Preface

Acknowledgments

About this Book

Author Online

About the Author

About the Cover Illustration

1. Introducing CORS

Chapter 1. The Core of CORS

Chapter 2. Making CORS requests

2. CORS on the server

Chapter 3. Handling CORS requests

Chapter 4. Handling preflight requests

Chapter 5. Cookies and response headers

Chapter 6. Best practices

3. Debugging CORS requests

Chapter 7. Debugging CORS requests

Appendix A. CORS reference

Appendix B. Configuring your environment

Appendix C. What is CSRF?

Appendix D. Other cross-origin techniques

Index

List of Figures

List of Tables

List of Listings

Table of Contents

Copyright

Brief Table of Contents

Table of Contents

Foreword

Preface

Acknowledgments

About this Book

Author Online

About the Author

About the Cover Illustration

1. Introducing CORS

Chapter 1. The Core of CORS

1.1. What is CORS?

1.2. CORS by example

1.2.1. Setting up the request

1.2.2. Sending the request

1.2.3. Processing the response

1.3. Benefits of CORS

1.3.1. Wider audience

1.3.2. Servers stay in charge

1.3.3. Flexibility

1.3.4. Easy for developers

1.3.5. Reduced maintenance overhead

1.4. Summary

Chapter 2. Making CORS requests

2.1. What is a cross-origin request?

2.2. Browser support for CORS

2.3. Using the XMLHttpRequest object

2.3.1. Sending an HTTP request

2.3.2. Handling the HTTP response

2.3.3. Including cookies on cross-origin requests

2.4. XDomainRequest object in Internet Explorer 8 and 9

2.4.1. Differences between XDomainRequest and XMLHttpRequest

2.5. Canvas and cross-origin images

2.6. CORS requests from jQuery

2.7. Summary

2. CORS on the server

Chapter 3. Handling CORS requests

3.1. Setting up the sample code

3.1.1. Setting up the sample API

3.1.2. Setting up the sample client

3.1.3. Running the sample app

3.2. Making a CORS request

3.3. Anatomy of a CORS request

3.3.1. The players in a CORS request

3.3.2. Lifecycle of a CORS request

3.4. Making a request with the Origin header

3.4.1. Viewing the Origin header

3.4.2. What is an origin?

3.4.3. Setting the Origin header

3.5. Responding to a CORS request

3.5.1. The Access-Control-Allow-Origin header

3.5.2. Access-Control-Allow-Origin with a wildcard (*) value

3.5.3. Access-Control-Allow-Origin with an origin value

3.5.4. Rejecting CORS requests

3.6. Summary

Chapter 4. Handling preflight requests

4.1. What is a preflight request?

4.1.1. Lifecycle of a preflight request

4.1.2. Why does the preflight request exist?

4.2. Triggering a preflight request

4.2.1. When is a preflight request sent?

4.3. Identifying a preflight request

4.3.1. Origin header

4.3.2. HTTP OPTIONS method

4.3.3. Access-Control-Request-Method header

4.3.4. Putting it all together

4.4. Responding to a preflight request

4.4.1. Supporting HTTP methods with Access-Control-Allow-Methods

4.4.2. Supporting request headers with Access-Control-Allow-Headers

4.4.3. Sending the actual request

4.4.4. Rejecting a preflight request

4.5. Recapping preflights

Successful preflight != successful request

JavaScript code and preflights

Preflights are stateless

Preflight requests and upload events

4.6. Preflight result cache

Setting the cache time with Access-Control-Max-Age

4.7. Summary

Chapter 5. Cookies and response headers

5.1. Supporting cookies in CORS requests

5.1.1. Setting cookies with a login page

5.1.2. Reading the cookie on the server

5.1.3. Including cookies in CORS requests

5.1.4. How withCredentials and Access-Control-Allow-Credentials interact

5.1.5. Caveats to cookie support

5.2. Exposing response headers to the client

5.2.1. Reading a response header

5.2.2. Adding response header support

5.3. Summary

Chapter 6. Best practices

6.1. Refactoring the sample code

6.2. Before you begin

6.3. Setting the Access-Control-Allow-Origin header

6.3.1. Allowing cross-origin access for everyone

6.3.2. Limiting CORS requests to a set of origins

6.3.3. CORS and proxy servers

6.3.4. Null origin

6.3.5. Origin header on same-origin requests

6.4. Security

6.4.1. Including cookies on requests

6.4.2. Authorizing requests using OAuth2

6.5. Handling preflight requests

6.5.1. Whitelisting request methods and headers

6.6. Reducing preflight requests

6.6.1. Maximizing the preflight cache

6.6.2. Changing your site to reduce preflight requests

6.7. Exposing response headers

6.8. CORS and redirects

6.9. Summary

3. Debugging CORS requests

Chapter 7. Debugging CORS requests

7.1. Solving CORS errors

7.2. Using the browser’s developer tools

7.2.1. Using the console

7.2.2. Using the Network tab

7.3. Monitoring network traffic

7.3.1. Using Wireshark

7.3.2. Using Fiddler

7.4. Using curl to simulate CORS requests

7.4.1. Making CORS requests using curl

7.4.2. Making preflight requests using curl

7.4.3. Why use curl?

7.5. Sending requests using test-cors.org

7.5.1. Sending requests to a remote server

7.5.2. Sending requests to the local server

7.5.3. Understanding how the client works

7.6. Tips for mobile debugging

7.6.1. Log requests on the server

7.6.2. Use test-cors.org

7.6.3. Use remote debugging tools

7.6.4. Use a mobile simulator

7.7. Getting help

7.8. Summary

Appendix A. CORS reference

A.1. HTTP headers

Request headers

Response headers

A.2. Other terms used in CORS

Simple method

Simple header

Simple response header

Appendix B. Configuring your environment

B.1. Setting up for the sample application

B.1.1. Node.js and NPM

B.1.2. Express

B.2. Debugging tools

B.2.1. Wireshark

B.2.2. Fiddler

B.2.3. Curl

B.3. Resources

Appendix C. What is CSRF?

C.1. What is CSRF?

C.2. Implementing CSRF protection for same-origin requests

Appendix D. Other cross-origin techniques

D.1. JSONP

D.2. Flash

D.3. postMessage and easyXDM

D.4. Server-side request

Index

List of Figures

List of Tables

List of Listings

Foreword

No one can argue that AJAX was an important advancement in the evolution of the web. In a few short years, a single technology (XMLHttpRequest) revolutionized how users interacted with our content. Instead of loading entire pages, portions of the page could refresh with minimal distraction to the user. In a time when broadband wasn’t the norm, this change was amazingly powerful.

The web grew up during that time. The birth of AJAX catalyzed the transformation of web pages into web apps, but it also paved the way for modern client-side development. Today’s JavaScript frameworks, which launched single page apps (SPAs), were a result of this early paradigm shift. But as more code moved off the server and into the client, it was clear XMLHttpRequest wasn’t keeping up. JavaScript’s single-origin policy suffocated our creative potential. Web developers like you and I developed clever techniques (JSONP and proxy servers) to wiggle around the restrictions, but ultimately, all our cleverness was just a bandage. Gone were the days of the mashup. Web services were becoming a ubiquitous back end for web applications. True dependencies in our applications are critical to making web services tick. However, for services to be accessible from JavaScript meant a better tool was needed for dealing with remote resources. Enter cross-origin resource sharing, better known as CORs.

CORs is a powerful addition in the evolution of XMLHttpRequest and the advancement of web apps. By definition, CORs creates a standard way for JavaScript to securely communicate with cross-domain resources. Practically speaking, it opens up a whole new world for front-end developers. CORs brings back flexibility to JavaScript developers and allows them to access APIs and services from anywhere on web. For example, organizations can publish read/write JSON APIs or make their entire data sets accessible to the world of JavaScript.

Monsur Hossain is fellow Googler and expert in cross-domain JavaScript communication. He and I first crossed paths working on Google’s XML-based Data APIs and later as engineers on Google’s JavaScript client library. Over the years, Monsur lead many facets of the client library, including its OAuth authentication flow and adding CORS support for APIs like YouTube and Google Drive.

CORs in Action is a well-rounded resource for developers wanting to learn the entire spectrum of CORs. Monsur does an excellent job of covering the basics. He highlights important sections with figures and provides excellent code snippets to teach by example.

I particularly like how often Monsur references the browser DevTools. It’s a critical tool for gaining insight into the browser’s network stack. His use of real-world APIs like Google Calendar and Flickr also give readers practical hands-on experience. I have no doubt you’ll walk away learning a great deal from CORs in Action.

ERIC BIDELMAN STAFF DEVELOPER RELATIONS ENGINEER GOOGLE

Preface

I first encountered cross-origin requests around 2006, when I joined Google and became the owner of the GData JavaScript Client. The GData JavaScript Client was a library that gave developers access to various Google APIs from JavaScript. The library itself was written in JavaScript, and the code was pretty straightforward...except for this little corner of code that made cross-origin requests to Google’s servers. This was before CORS existed, so this little corner jumped though crazy hoops to load data from Google’s APIs. From the developer’s perspective, the code simply worked. But between the request and the response was a dark and convoluted maze of code that was difficult to understand and debug.

So you can imagine my happiness when I discovered CORS. Here was a clean, simple, and standard way for making cross-origin requests. Instead of code that’s difficult to understand, I could have simple HTTP response headers. Instead of code that’s difficult to debug, I could have a single standard that worked across all browsers. I quickly set out to add support for CORS to Google’s APIs.

And that’s when the real fun started. While CORS uses HTTP headers to enable cross-origin requests, there are many subtle ways in which these headers can interact. It’s not as simple as adding an HTTP header to your server and calling it a day. And because CORS was such a new feature, there weren’t a lot of resources to guide me. Armed with the CORS spec, Wireshark, and a lot of patience, I spent the next few weeks building a flexible and configurable CORS library that could work for various types of requests. Based on that experience, I started contributing CORS knowledge to the community by participating in Stack Overflow and writing an article about CORS for HTML5Rocks.com.

That was almost three years ago, and in the years since, CORS has grown from a specification to a feature supported by most major APIs. You can find CORS support in APIs from Amazon, Dropbox, Facebook, Flickr, Google, and GitHub (to name just a few). This book distills those three years of experience into an easy and illuminating resource for learning CORS. My hope is that this book helps make CORS a little less daunting, and encourages you to add CORS support to your own systems. Open access to information is a cornerstone of the web, and CORS is one of the ways to enable this. The more developers become comfortable with CORS, the more it will become a part of the everyday vocabulary of the web.

Acknowledgments

This book would have never come together were it not for the generous support from many individuals. I’d like to take a moment to acknowledge them here.

Thank you to all the Googlers who helped guide my own understanding of CORS, including Eric Bidelman, Jad Boutros, Antonio Fuentes, Joe Gregorio, Jason Hall (whose prompting led me to investigate CORS in the first place), Yaniv Inbar, Sven Mawson, Eduardo Vela Nava, Jeffrey Posnick, Louis Ryan, Benjamin Carl Wiley Sittler, and Mark Stahl. And special thanks to Eric for contributing the foreword to the book.

Thank you to Anne van Kesteren for authoring the CORS spec that made this book possible, to Evan Hahn and Will Stranathan for their insights on particularly thorny areas of this book, and to Nicholas Zakas, whose blog post was my first introduction to CORS. Michael Hausenblas, thank you for starting enable-cors.org, and passing the torch to me.

Thank you to everyone at Manning for their support and guidance during the crafting of this book. To my editors Cynthia Kane and Monique Bos, thank you for the readings and rereadings that elevated the chapters to the next level. To Konstantin Yakushev, thank you for your in-depth technical review across multiple platforms. Thank you also to Michael Stephens, Kevin Sullivan, Jodie Allen, Deepak Vohra, Elizabeth Martin, and Chuck Larson.

Thank you to the reviewers who took time to read the manuscript at various stages of its development and who provided invaluable feedback: Christopher Haupt, Cristian Antonioli, Jeroen Benckhuijsen, Joshua Frederic, Margriet Bruggeman, Nickie Buckner, Nikander Bruggeman, Roger Keizer, Roger Le, and Tom Rutka.

Thank you to Amma, Abba, Mom, Dad, Irene, Marvin, Seema Apa, and Jav Bhai for your enthusiasm and support. And finally, thank you to my wife, Suraiya, whose patience, advice, understanding, and love were necessary ingredients for writing this book.

About this Book

The idea behind CORS is simple: allow one site to make a request to another. It’s a fairly trivial thing to do from most programming languages. So why does there need to be a book about it?

Hidden behind this simple idea are a lot of complex concepts. While other programming languages have no restrictions on HTTP requests, things are different in a browser, where the browser’s same-origin policy prevents requests from different sites. CORS must balance the need to enable cross-origin requests while preserving the same-origin policy for sites that don’t use CORS.

Also, CORS has both a client- and a server-side component. For a cross-origin request to succeed, the client and the server must be in agreement. This is different from other web technologies. For example, CSS lives solely in the client-side code; there is no server-side component.

This book serves as an introduction to CORS and attempts to demystify the issues that make CORS complicated.

What this book will give you

Here is an overview of the topics this book will cover:

CORS from the client—This book starts by looking at how to make CORS requests from JavaScript code. It introduces the XMLHttpRequest object, which can be used to make CORS requests. While the XMLHttpRequest object may be familiar to JavaScript developers, the book focuses on what is unique about CORS. The book also covers alternative mechanisms for making CORS requests, such as images in canvas elements, media uploads, and using JQuery.

CORS from the server—The server uses HTTP headers to control CORS behavior. HTTP headers can be used to indicate things like which HTTP methods are allowed, whether cookies can be included on requests, and whether cross-origin requests are allowed at all. This book takes an in-depth look at what these headers are and how they’re used.

Debugging CORS requests—Because CORS has client and server components, it can sometimes be difficult to debug CORS issues when things go wrong. This book ends with a look at how to debug issues with CORS requests. It introduces such tools as the browser’s debugging tools, Wireshark, and Fiddler.

What this book won’t give you

This book isn’t an introduction to JavaScript or the web. This doesn’t mean you need to be a JavaScript expert. It assumes that you have a basic understanding of how the web, HTTP requests, and JavaScript work.

Although this book uses Node.js and Express for the sample code, you won’t find fully programmed CORS solutions for your specific language or platform (unless, of course, you happen to be using Node.js and Express). The core concepts of CORS are the same regardless of what web platform or programming language you use. The goal of this book is to give you the foundation for understanding CORS, so that you can then go off and implement it on your own platform.

How to read this book

Because this book is an overview of CORS, you can approach it from different perspectives:

API owners—Whether you maintain an existing API or are building a new API from scratch, CORS is a great way to extend your API’s reach.

API consumers—Building dynamic sites on top of APIs can sometimes be difficult. CORS can make this easier by giving developers a pure JavaScript mechanism for making API requests.

JavaScript developers—Even if you aren’t making CORS requests, JavaScript developers can benefit from understanding the basics of how XMLHttpRequest and CORS work. Most modern web pages are built on top of asynchronous HTTP requests (AJAX), and it’s useful to have CORS as another tool in your toolbox.

Roadmap

This book is divided into three parts. The first part looks at how to make CORS requests from the browser. The second part looks at how to add CORS support to a server. The third part looks at how to debug CORS requests.

Part 1: Introduction to CORS

Chapter 1 begins by giving an overview of what CORS requests are and how they work. It then dives into CORS with an example that makes cross-origin requests to the Flickr API.

Chapter 2 introduces the XMLHttpRequest object, which can be used to make cross-origin requests. Next, it covers the XDomainRequest object, which is used to make CORS requests from Internet Explorer 8 and 9. Then it covers other places where