MEAP Edition Manning Early Access Program OpenID Connect in Action Version 7 Copyright 202 Manning Publications 2 For more information on this and other Manning titles go to manning.com ©Manning Publications Co. To comment go to liveBook welcome Thank you for purchasing the MEAP for OpenID Connect in Action. In this book you will learn everything you need to know about OpenID Connect, and we don’t expect you to know about anything other than OpenID Connect is being used for login. The sample applications in the book use Java, React, and React Native. So, having some working knowledge of those technologies will be helpful, but is not a must. If you are comfortable with any programming language and know the basics of JavaScript, and have a solid understanding of how the web works in general, you are all set to get started. Appendix A and B of the book help you get a jumpstart with React and React Native respectively. When I joined WSO2 in 2007, my first task was to implement OpenID support to the open source Identity Server, which was called Identity Solution those days. Couple of years later, in 2009, we had a large-scale deployment of Identity Server as an OpenID provider in Saudi Arabia over a 4 million user base. That was my first hands on experience with OpenID. OpenID was the predecessor of OpenID Connect. Later I also implemented OAuth 1.0 support, and some part of the OAuth 2.0 support in the Identity Server product. When OpenID Connect became mainstream, we added the OpenID Connect support to the Identity Server. Over the time I’ve seen how more and more applications adding support for OpenID Connect, and easily taking over its most successful predecessor, SAML 2.0. In the last 5 years most of the applications developed globally use OpenID Connect for login. OpenID Connect now being used to secure access to all types of applications. In the book I primarily focus on four types of applications: single-page applications, native mobile applications, smart TV applications and server-side web applications. I picked these four types of applications, because they do address almost all the common use cases of OpenID Connect we see in practice today. In addition to explaining OpenID Connect internals in detail, while taking you through how different applications integrate with OpenID Connect, the book also covers security pitfalls, and the best practices & guidelines to avoid those while integrating client applications with OpenID Connect for login. I hope you’ll find the book useful. Please be sure to post any questions, comments, or suggestions you have about the book in the liveBook discussion forum. Your feedback is essential in developing the best book possible. —Prabath Siriwardena brief contents 1 The OpenID Connect landscape 2 The cornerstone of OpenID Connect 3 Securing access to a single-page application 4 The building blocks of an ID token 5 Requesting and returning claims 6 Securing access to a server-side web application 7 Logging out 8 Claim-based access control with Open Policy Agent (OPA) 9 Securing access to a native mobile application 10 Mitigating common threats and vulnerabilities APPENDIXES A React fundamentals B React Native fundamentals ©Manning Publications Co. To comment go to liveBook 1 1 The OpenID Connect landscape This chapter covers • What is OpenID Connect and why? • How OpenID Connect differs from OpenID, SAML 2.0 Web SSO and OAuth 2.0? • What is identity federation and single-sign-on (SSO)? • The benefits of having one trusted identity provider for multiple client applications • The use cases of OpenID Connect Even if you don’t have hands-on developer experience in integrating OpenID Connect with your web or mobile applications for login, the chances are very high that at some point in your life you have used OpenID Connect to log into some web or mobile application. If you have ever used Log in with Apple ID or Log in with Google, you have used OpenID Connect underneath. 1 In simple terms, OpenID Connect is a standard that defines how a client application communicates with an identity provider to identify a user.2 A client application can be single- page application, a native mobile application, a server-side web application and so on. We discuss in the rest of the book how to integrate OpenID Connect with all these types of applications. An identity provider is a generic term for an entity that manages user attributes and credentials. The users can log into client applications via an identity provider following some kind of a protocol. This protocol can be a standard protocol that is widely accepted, or a proprietary protocol that is specific to a vendor. An OpenID Provider is an identity provider 1 Coursera (https://www.coursera.org), for example, the famous online learning platform, supports login with both Apple ID and Google ID. Hotels.com, eBay, Bloomberg, Reddit, Meetup, Ups, Rakuten, and many more also support login with both Apple ID and Google ID. 2 OpenID Foundation has defined the standard for OpenID Connect and the core specification is available at https://openid.net/specs/openid-connect- core-1_0.html. ©Manning Publications Co. To comment go to liveBook 2 that supports OpenID Connect, as the standard protocol to communicate with client applications.3 OpenID Connect is not the only standard out there or the only option you have, to integrate with your web and mobile applications for login. But, by far, and also in the foreseeable future, OpenID Connect is the most widely adopted technology for login among greenfield applications. Perhaps that’s why you’ve invested in a book on OpenID Connect. You’ve made the right decision! Understanding how OpenID Connect works, integrating OpenID Connect with your web and mobile applications, and understanding the role of OpenID Connect in securing your APIs/microservices are key skills every developer should possess. In this book you will learn everything you need to know about OpenID Connect, and we don’t expect you to know about anything other than OpenID Connect is being used for login. The sample applications in the book use Java, React, and React Native. So, having some working knowledge of those technologies will be helpful, but is not a must. If you are comfortable with any programming language and know the basics of JavaScript, and have a solid understanding of how the web works in general, you are all set to get started. Appendix A and B of the book help you get a jumpstart with React and React Native respectively. 1.1 What is OpenID Connect? OpenID Connect is a standard developed by the OpenID foundation, on top of OAuth 2.0 specification (https://tools.ietf.org/html/rfc6749). OAuth 2.0 is an authorization framework for access delegation. You can also call OpenID Connect an identity layer built on top of OAuth 2.0.4 To understand OpenID Connect in detail, having a good understanding of OAuth 2.0 is a must. The chapter 2 of the book covers OAuth 2.0 essentials that you need to know to follow this book. Also, if you’d like to delve deep into OAuth 2.0, we recommend the books, OAuth 2.0 in Action by Justin Richer and Antonio Sanso (Manning Publications, 2017) and Advanced API Security: OAuth 2.0 and Beyond by Prabath Siriwardena (Apress, 2019). In a typical OpenID Connect login flow, there are two main parties involved in addition to the end user: the OpenID provider and the client application. The OpenID provider manages user attributes and credentials, and lets the users log in to client applications following the OpenID Connect protocol. These client applications and OpenID provider can belong to the same organization or different organizations. When a client application comes from an outside organization from where the OpenID provider belongs to, we call that client application a third-party client application. When you log in to eBay with your Apple ID, for example, eBay is the client application and Apple is the OpenID provider. They belong to two different organizations. You can call eBay a third-party client application. The client applications rely on an OpenID provider to authenticate users. In this book we mostly focus on integrating client applications securely with an OpenID provider. We won’t teach you how to write an OpenID provider, but will help you understand the role of an OpenID provider and what you need to worry about when picking an OpenID provider for your project. We’ll use popular open-source OpenID providers in our samples, and since how 3 In general we call the identity provider that supports OpenID Connect standard, an OpenID provider – not an OpenID Connect provider. 4 OAuth 2.0 is about authorization, while OpenID Connect is about authentication. OpenID Connect uses the OAuth 2.0 protocol to transport attributes related to a user’s identity from an identity provider to a client application. ©Manning Publications Co. To comment go to liveBook 3 you set up those tools could vary time to time with new releases, we’ll keep the setting up steps of those OpenID providers outside the book, in our GitHub repository (https://github.com/openidconnect-in-action/samples). In simple terms, OpenID Connect is a standard that defines how a client application communicates with an OpenID provider to identify a user. How exactly the communication between a client application and the OpenID provider takes place is defined in the OpenID Connect Core specification (https://openid.net/specs/openid-connect-core-1_0.html) developed by the OpenID foundation. There are few more specifications developed by the OpenID foundation to address some other use cases around OpenID Connect. As we delve deep into OpenID Connect, we’ll introduce you to those specifications. Also, in section 1.8 we discuss OpenID Connect use cases. Figure 1.1: The OpenID Connect specification defines how a client application can authenticate a user by talking to an OpenID provider. It further defines how exactly the messages being passed between the client application and the OpenID provider. Figure 1.1 shows a typical OpenID Connect flow at a very highlevel. From the user’s point of view, its quite similar to an OAuth 2.0 authorization code grant type, which you’ll learn in chapter 2. You’ll learn in detail, what exactly happens under each arrow in chapter 3. However, following lists out the communications happen between the client application, OpenID provider and the end user at a highlevel. • In step 1, the client application redirects the user to the OpenID provider for authentication. On eBay for example, once you click on Login with Google you are redirected to Google for authentication. • The OpenID provider first checks whether the user has a valid session under the domain of the OpenID provider, and if not, in step 2, challenges the user to authenticate. Also, will show the end user which user attributes the client application is requesting. This step is outside scope of the OpenID protocol, and different OpenID ©Manning Publications Co. To comment go to liveBook 4 providers have implemented this in different ways. • In step 3, the end user authenticates to the OpenID provider and gives or rejects their consent to share the requested attributes with the client application. This step is also outside scope of the OpenID protocol. • In step 4, the OpenID provider redirects the user back to the client application. Based on the OpenID Connect authentication flow you use (which we discuss in chapter 3), this step may return the requested attributes directly to the client application, or a temporary token that can be exchanged to the requested attributes via another direct call happens between the client application and the OpenID provider. 1.2 An alternative view of OpenID Connect As we discussed in section 1.1 the most common way of looking at OpenID Connect is as an identity layer built on top of OAuth 2.0. There is another way of looking at OpenID Connect. It’s a specification, which defines the followings: • A schema for a token (which is a JSON Web Token (JWT)) and a set of processing rules around it. A JWT is a container to transport a set of claims (a set of attributes) from one point to another point in a cryptographically safe manner. You’ll learn more about JWT in chapter 4. The OpenID Connect specification identifies this token, as the ID token and you will learn more about ID token in chapter 5. Following is a decoded ID token and only shows the header and the body parts.5 The third part is the signature of body, which is not shown. { "alg": "RS256", "kid": "1e9gdk7" } { "iss": "http://server.example.com", "sub": "248289761001", "aud": "s6BhdRkqt3", "nonce": "n-0S6_WzA2Mj", "exp": 1311281970, "iat": 1311280970 } • A transport binding, which defines how to transport an ID token from one point to another. OpenID Connect specification uses the term, authentication flows, to define multiple ways how you can transport an ID token from one point to another. Most of the applications of OpenID Connect use both the token type and the transport binding, for example when you use Login with Google on eBay. But, still there are some applications that rely on only the token type (the ID token). Those applications use ID token as the contract to transfer attributes in cryptographically safe manner. For example, Kubernetes uses an ID token to authenticate to the Kubernetes API server, and SPIFFE JWT SVID profile defines the structure of the JWT as an ID token.6 5 A JWT can be a JWS (JSON Web Signature) or a JWE (JSON Web Encryption). In practice most of the time an ID token is a JWS. However it can be a JWE as well. If an ID token is a JWS, then it has three parts, and if the ID token is a JWE, then it has five parts. For further details please check chapter 4. 6 If you are new to Kubernetes and/or SPIFFE please check the Appendix H and Appendix J of the book, Microservices Security in Action (Manning Publications, 2020) by Prabath Siriwardena and Nuwan Dias. ©Manning Publications Co. To comment go to liveBook 5 1.3 OpenID Connect vs. OpenID OpenID Connect has its roots in OpenID. In fact OpenID is the predecessor of OpenID Connect. There is a chance that you might not have heard of OpenID, or think OpenID is synonymous to OpenID Connect – they are not. OpenID is a specification developed by OpenID foundation (the same entity behind OpenID Connect) in 2005, as a way of facilitating login to a client application (OpenID uses the term relying party to represent a client application), via an identity provider the user picks. The end user experience is very much similar to what you experience today when you login to eBay using your Apple ID or Google ID. But how the protocol works underneath is completely different. Today no one uses OpenID except Amazon and Googereads. Surprisingly, Amazon still uses OpenID (at least at the time of this writing). Try to sign into amazon.com or log in to goodreads.com via the Signing with Amazon option; you will see how OpenID works. OpenID Connect is not OpenID and the two are not compatible with each other. Even though conceptually they try to address the same problem at a high level, OpenID Connect’s design is totally different from that of OpenID. So, the best part of it is, to learn OpenID Connect, you don’t need to know anything about OpenID.7 Also, unlike OpenID, OpenID Connect is enterprise ready! Also, in most of the time, today if someone just says OpenID, that probably means OpenID Connect. 1.4 OpenID Connect vs. OAuth 2.0 As we discussed in section 1.3, OpenID Connect is not compatible with its predecessor, OpenID. Unlike OpenID, OpenID Connect is built on top of OAuth 2.0. From here onwards, in this book, when not mentioned explicitly, whenever we say OpenID, we are referring to OpenID Connect. OAuth 2.0, which is defined in the RFC 6749, is an authorization framework for access delegation. OpenID Connect builds an identity layer on top of OAuth 2.0. We’ll discuss what this really means later in this section. If you are new to OAuth 2.0, the chapter 2 of the book will help you understand it better. Having a good understanding of OAuth 2.0 is a must to understand how OpenID Connect works. An OpenID provider is always an OAuth 2.0 authorization server, yet the reverse is not true all the time.8 For example, Facebook supports OAuth 2.0, so we can call it an authorization server, but we cannot call Facebook an OpenID provider, because it does not support OpenID Connect. 7 OpenID is an obsolete protocol today. However if you are interested in reading more about OpenID, please check this presentation done by Prabath Siriwardena (the author of this book) in 2008: https://www.slideshare.net/prabathsiriwardena/understanding-openid. 8 In general we call the identity provider that supports OpenID Connect standard, an OpenID provider – not an OpenID Connect provider. ©Manning Publications Co. To comment go to liveBook 6 Figure 1.2: A typical OAuth 2.0 authorization code grant type flow. The client application, following the authorization grant type obtains an access token from the authorization server to access a resource on behalf of the user (the resource owner). One of the key features in OAuth 2.0 is grant types. A grant type defines how a client application can get an access token from an OAuth 2.0 authorization server (see figure 1.2). This access token lets the client application accesses a resource (an API, a microservice) on behalf of the owner of the resource. If a client application, for example, wants to access your Facebook photos via the Facebook API (GET graph.facebook.com/me/photos), the client application first has to obtain an access token from the Facebook authorization server, with your consent, and use that access token along with the API call to access the photos. The photos are the resources and you are the resource owner. The me, in above API represents you, or the owner of the resource, or the owner of the access token. The following table summarizes the mapping between OAuth 2.0 terminolgy and Facebook terminology. ©Manning Publications Co. To comment go to liveBook