OpenID Connect - End-user Identity for Apps and APIs: API-University Series, #6

By Matthias Biehl

Signup and login with a Google, Yahoo, or Microsoft account can be found in more and more web and mobile apps. One login used by many, freeing the end-user from the burden of managing many accounts and passwords. Signup and login to a new app become so smooth and convenient, that end-users are much more likely to try a new app.

For us developers of web and mobile apps, these signup and login features are attractive, too: we do not need to manage user credentials, and we get a higher conversion rate resulting in more new customers. In effect, this means cutting costs and increasing the number of new customers for our apps.

So how does this feature "Signup and login with Google, Yahoo, or Microsoft" work? It is realized with OpenID Connect, a standardized protocol for sharing end-user data in a secure and controlled manner. Exploring how OpenID Connect works, so we as developers can enjoy its benefits is the subject of this book.

This book explains the overall concept of OpenID Connect, so we understand who the actors are, which endpoints and tokens are involved and how these elements interact in so-called flows. These flows tend to get confusing, so we visualize these flows as sequence diagrams, and show how to choose the flow that is appropriate for a given scenario. Using examples, we explore how the tokens are constructed, signed and encrypted with JWT, JWS, and JWE.

This is not a programming book, don't expect implementations with a specific programming language or library. Instead, we focus on understanding OpenID Connect on a conceptual level, so we can design and architect apps that work with OpenID Connect. And OpenID Connect is the standard behind creating smooth login and signup experiences, increasing the customer signup rate, and creating highly converting apps.

• Language: English
• Publisher: API-University Press
• Release date: Feb 3, 2019
• ISBN: 9781979718479

Book preview

OpenID Connect

End-user Identity for Apps and APIs

Matthias Biehl

OpenID Connect

OpenID Connect

Abstract

1 Introduction

1.1 What is OpenID Connect

1.2 How does OpenID Connect Work

1.2.1 Claims on the Userinfo Endpoint

1.2.2 Claims in the Identity Token

1.3 OAuth 2 vs. OpenID Connect

1.4 Common Misunderstandings

1.5 Perspective of the End-user

Advantages for the End-user

1.6 Perspective of the App Provider

Advantages for the App Provider

1.7 Perspective of the OpenID Connect Provider

Advantages for the OpenID Connect Provider

1.8 OpenID Connect Cheat Sheet

2 OpenID Connect Actors

2.1 OpenID Connect Provider

2.2 Resource Provider

2.3 End-user (a.k.a. Resource Owner)

2.4 Client (a.k.a. App)

3 OpenID Connect Endpoints

3.1 Authorization Endpoint

3.1.1 Behavior of the Authorization Endpoint

3.1.2 Input Parameters

3.1.3 Output

3.1.4 Scope

3.1.5 Claims

3.2 Resource Endpoint

3.3 Userinfo Endpoint

3.3.1 Interactions on the Userinfo Endpoint

3.3.2 Requirements

3.3.3 Claims on the UserInfo Endpoint

3.4 Token Endpoint

3.4.1 Input Parameters

3.4.2 Credentials

3.4.3 Output

3.4.4 Validations at the Token Endpoint

3.5 Redirect Endpoint

3.5.1 Why is this so complicated?

3.5.2 Details of the Redirect Endpoint

3.5.3 Implementing the Redirect Endpoint

4 Tokens in OpenID Connect

4.1 Token Types

4.1.1 Reference Tokens

4.1.2 Value Tokens

4.1.3 Token Types in OpenID Connect

4.2 Access Token

4.2.1 Access Token Validation

4.3 Refresh Token

4.4 Authorization Code

4.5 ID Token

4.5.1 Example ID Token

4.5.2 Claims

4.5.3 ID Token Validation

5 OpenID Connect Flows

5.1 Authorization Code Flow

5.1.1 Authorization Endpoint

5.1.2 Redirect Endpoint

5.1.3 Token Endpoint

5.1.4 Token Validation

5.1.5 Access Protected Endpoint

5.2 Refresh Flow

5.3 Implicit Flows

5.4 Implicit Flow with id_token & token

5.4.1 Authorization Endpoint

5.4.2 Redirect Endpoint

5.4.3 Token Validation

5.4.4 Access Protected Endpoint

5.5 Implicit Flow with id_token

5.5.1 Authorization Endpoint

5.5.2 Redirect Endpoint

5.5.3 Token Validation

5.6 Hybrid Flows

5.7 Hybrid Flow with code & id_token & token

5.7.1 Authorization Endpoint

5.7.2 Redirect Endpoint

5.7.3 Token Validation for Hybrid Flow

5.7.4 Token Endpoint

5.7.5 Resource Endpoint

5.8 Hybrid Flow with code & id_token

5.8.1 Authorization Endpoint

5.8.2 Redirect Endpoint

5.8.3 Token Validation

5.8.4 Token Endpoint

5.8.5 Resource Endpoint

5.9 Hybrid Flow with code & token

5.9.1 Authorization Endpoint

5.9.2 Redirect Endpoint

5.9.3 Token Validation

5.9.4 Token Endpoint

5.9.5 Resource Endpoint

6 Client Setup for OpenID Connect

6.1 Choosing A Suitable OpenID Connect Flow

6.2 Client Registration

6.3 Redirect Endpoint Implementation

6.3.1 Receive the Parameters

6.3.2 Validate and Store the Parameters

6.3.3 Initiate the Next Step in the Flow

6.4 Initiation of OpenID Connect Flow

6.5 Access to Resource Endpoints and Userinfo Endpoint

7 JSON Token Infrastructure

7.1 JSON Web Token (JWT)

7.1.1 Using JWT

7.1.2 JWT Claims

7.1.3 JWS and JWE - Signature and Encryption

7.1.4 Format of a Signed JWT

7.1.5 JWT Verification

7.1.6 Distinguishing if a JWT is JWE or JWS

7.2 JSON Web Signature (JWS)

7.2.1 JWS Format

7.2.2 JWS Serialization

7.2.3 JWS Example

7.3 JSON Web Encryption (JWE)

7.3.1 JWE Format

7.3.2 JWE Serialization

7.3.3 JWE Example

7.4 JSON Web Key (JWK) and JSON Web Key Set (JWKS)

7.5 JSON Web Algorithm (JWA)

7.5.1 MAC Algorithms for JWS

7.5.2 Content Encryption Algorithms for JWE

7.5.3 Key Encryption Algorithms for JWE

8 Appendix

Newsletter with FREE Bonus Material

About the Author

Feedback

Other Products by the Author

API-University Book Club

Book on OAuth 2.0

Book on OpenID Connect

Book on API Architecture

Book on RESTful API Design

Book on Webhooks

Book on GraphQL API Design

Book on REST & GraphQL

Book on Serverless GraphQL APIs with AWS AppSync

Book on Making Money with Alexa Skills - A Developer’s Guide

Online Course on OAuth 2.0

Online Course on RESTful API Design

References

Table of contents

OpenID Connect

OpenID Connect

Copyright 2019 by Matthias Biehl

All rights reserved, including the right to reproduce

this book or portions thereof in any form whatsoever.

Book cover contains elements designed by Freepik.

Biehl, Matthias

API-University Press

Volume 6 of the API-University Series.

Includes illustrations, bibliographical references and index.

Built:

ISBN-13: 978-1979718479

ISBN-10: 1979718474

API-University Press

https://www.api-university.com

[e-mail]

Abstract

Signup and login with a Google, Yahoo, or Microsoft account can be found in more and more web and mobile apps. One login used by many, freeing the end-user from the burden of managing many accounts and passwords. Signup and login to a new app become so smooth and convenient, that end-users are much more likely to try a new app.

For us developers of web and mobile apps, these signup and login features are attractive, too: we do not need to manage user credentials, and we get a higher conversion rate resulting in more new customers. In effect, this means cutting costs and increasing the number of new customers for our apps.

So how does this feature Signup and login with Google, Yahoo, or Microsoft work? It is realized with OpenID Connect, a standardized protocol for sharing end-user data in a secure and controlled manner. Exploring how OpenID Connect works, so we as developers can enjoy its benefits is the subject of this book.

This book explains the overall concept of OpenID Connect, so we understand who the actors are, which endpoints and tokens are involved and how these elements interact in so-called flows. These flows tend to get confusing, so we visualize these flows as sequence diagrams, and show how to choose the flow that is appropriate for a given scenario. Using examples, we explore how the tokens are constructed, signed and encrypted with JWT, JWS, and JWE.

This is not a programming book, don’t expect implementations with a specific programming language or library. Instead, we focus on understanding OpenID Connect on a conceptual level, so we can design and architect apps that work with OpenID Connect. And OpenID Connect is the standard behind creating smooth login and signup experiences, increasing the customer signup rate, and creating highly converting apps.

One more thing before we get started ...

As a reader of this book, you have free access to the API-University Best Practice Newsletter. Free bonus material and amazing freebies are waiting for subscribers, such as the popular OAuth Cheat Sheet.

1 Introduction

For us web and mobile app developers, authentication and identity management is a big pain point. We understand that it is critical from an information security perspective, since we are dealing with personal data, so we better get it right. This means setting up a secure infrastructure for authentication and storing user identity, maintaining it with constant security patches and providing end-user support, e.g. for lost passwords, changed address, changed email and a lot more. It simply means a lot of overhead and does not deliver any differentiating features to win new users. But signup and login are not only difficult to build and operate, but it is often inconvenient to use.

End-users are not very fond of filling in long signup forms, and if we require it in an app, it usually hurts conversion, number of signups, usage and ratings of the app. End-users tend to shy away from tedious onboarding processes or only get halfway through before they give up. Those users may never return.

So how do some of the most successful and popular apps deal with this situation? Have they found a solution, which may be the secret of their success?

To find out, let’s study the user experience when signing up for their app. When signing up as a user for such an app, we can choose to identify with our existing Google,