Table Of ContentMEAP 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
