Jerreck McWilliams .NET Dev in DFW

OAuth 2.0, OpenID Connect, and Identity Server 4 (Work in Progress)

This article is a high-level cited overview of OAuth 2.0, OpenID Connect, and Identity Server 4 with additional resources at the end if you'd like to learn more.

It's part of a series of tutorials that are meant to give a .NET developer new to token based authentication enough of a foundation to be confident in the decisions they make when implementing an instance of Identity Server 4 to secure an API. Code exmaples are in C# and .NET Core 3.1.

Table of Contents

Overview

Last summer, I spent a few weeks learning about OAuth 2.0, OpenID Connect, and Identity Server 4 along with my coworkers in the context of implementing an instance of Identity Server 4 that's since been running in production for some internal apps while we evaluate it.

Pretty much all of us agreed that it was difficult to find info about any of this that was both authoritative and accurate - mostly because we didn't know who the experts were and even the folks who seemed to be experts would often contradict each other, so I wrote this article to aggregate the best info that we found and tried to present it in a a more easily digestible format.

Although I later cover some specifics about Identity Server 4, the info on OAuth 2.0 and OpenID Connect should be useful to you regardless of what implementation of them you're working with.

Despite doing a considerable amount of reading on this subject, that doesn't make me an expert, so treat this article as a cliffs notes version of the sources I've cited - those folks are the experts. The folks I'm citing are the ones who contributed to the OAuth 1.0, OAuth 2.0, and OpenID Connect specs as well as developed Identity Server.

Also, if I felt like someone did a better job of writing something then I could, I linked to it instead of rehashing it.

If you find errors in this article, please shoot me a message on LinkedIn with what I got wrong so I can correct it.

The Goal

We're going to build an authorization server using Identity Server 4. By the end of this article, you should have a working instance of Identity Server 4 using the authorization code flow with PKCE extension as well as a simple RESTful WebAPI with methods that require a valid bearer token from our authorization server in order to run successfully. We'll also build a GrapQL API using HotChocolate and demonstrate how authorization is different for GrapQL vs REST.

Identity and Access Management Basics

One of the barriers to my learning on this subject was my limited understanding of Identity and Access Management (IAM) basics. None of my prior work involved anything beyond simple username and password setups, so I had to do a lot of learning about IAM before I could really grok most of this.

IAM is a topic that's too big for one article and I'm certainly not an authority on it. If you'd like to dig deep into this subject I recommend reading CISSP: A Comprehensive Beginners Guide on the Information Systems Security by Walker Schmidt.

If you'd like a 15-minute read, this wikipedia article does on OK enough job to give you some context for this article.

However, it's going to be difficult to go further unless we define the following:

Authentication and Authorizaiton

For authentication and authorization, read this article that was published as part of a series of articles on Kerberos by (near as I can tell at least) Robert G Carter at Duke University. Sidenote: don't even worry about what Kerberos is if you're not familiar with it. It's not relevant to this discussion.

Delegation and Delegated Authorization

For delegation and delegated authorization, I recommend reading Delegation-based Security Model for Web Services by Wei She, Bhavani Thuraisingham, and I-Ling Yen at University of Texas at Dallas in Richardson, TX (CTRL + F "Delegation").

Bearer Tokens

For bearer tokens, read the definition of bearer token in RFC 6750 The OAuth 2.0 Authorization Framework: Bearer Token Usage.

Also, if you came across this answer on StackOverflow, be aware that it implies bearer tokens and refresh tokens are the same thing - they are not. You can read the definition of refresh token in RFC 6749 - The OAuth 2.0 Authorization Framework

JSON Web Tokens (JWT)

For JWTs, read Introduction to JSON Web Tokens and RFC 7519 - JSON Web Token (JWT).

Just as an FYI, JWT is commonly pronounced "jot."

OAuth 1.0

You do not need to learn OAuth 1.0 in order to use OAuth 2.0. OAuth 2.0 is actually not backwards compatible with OAuth 1.0 and OAuth 1.0 is not a secure protocol to use anymore.[#] However, I've included a bit about it here for some historical context.

OAuth 1.0 is a protocol for authorization. Specifically, it's a protocol for delegated authorization.[#] It was written and maintained by the OAuth working group at the Internet Engineering Task Force (IETF)

Delegated authorization over the internet was a huge challenege prior to OAuth 1.0 as was identity and access management (IAM) in general, because the internet was built without a way to know who and what you are connecting to.

A lot of techniques were developed to address this, but most of them suffered from either huge security flaws or from interoperability because so many different companies and organizations were making their own APIs for IAM.[#]

As a result, a group of developers from Twitter, Google, and OpenID and some other IAM experts came together and developed the first draft of the OAuth 1.0 spec in 2007.[#] This spec was later revised in 2009 and 2010.

If you would like to learn more about OAuth 1.0 and it's development, I highly recommend reading Eran Hammer's blog. He was the editor for the first draft and wrote about its development at the time. He also was the editor for most of the development of OAuth 2.0 before leaving its working group and offers an interesting perspective on its development.

I would recommend starting with Explaining OAuth published on September 5th, 2007.

I would also recommend reading The Laws of Identity by Kim Cameron for some context on the state of IAM prior to OAuth 1.0.

OAuth 2.0

OAuth 2.0 is a framework for delegated authorization that improved on some aspects of OAuth 1.0.[#]. It is written and maintained by the OAuth working group at the IETF.

OAuth 2.0 is not a protocol

Although it might seem pedantic, I think it's important to explain why OAuth 2.0 is not a protocol. Oauth 2.0 and the Road to Hell by Eran Hammer and OAuth is not a protocol by Ivan Sagalaev already did a great job of that, but the gist is that since OAuth 2.0 leaves some details up to the implementer, that makes it not a protocol and is why it was renamed "The OAuth 2.0 Authorization Framework"

You'll still see a ton of authoritative sources refer to it as a protocol and it honestly doesn't matter if you're using someone's implementation of OAuth 2.0, but I was always confused about why it was called seemingly different things - so there you go.

How OAuth 2.0 works

This subject has been written to death. For a free source, I would recommend taking a look at OAuth 2 Simplified (the blog post) by Aaron Parecki. Aaron is the author of OAuth 2 Simplified (the book) and maintains OAuth.net.

OAuth2 In Action by Justin Richer and Antonio Sanso is also an excellent read which covers both OAuth 2.0 and OpenID Connect.

Differences between OAuth 2.0 and OAuth 1.0

This is one of those times where I'm gonna be lazy. This question on Stackoverflow has a lot of excellent cited answers that do a great job of highlighting the major differences bewteen the two.

Authorization Code Flow with PKCE

I'm going to save you a ton of time and let you know that if you're just trying to secure a vanilla web service without needing to do anything IoT-related, then you're most likely going to want to use the authorization code flow along with the PKCE extension.

Fortunately for you, Implement the OAuth 2.0 Authorization Code with PKCE Flow by Micah Silverman at okta does an excellent job of doing that. It wasn't published at the time we were implementing Identity Server, so I'm kinda jealous.

OpenID Connect

OpenID Connect is an identity layer built on top of OAuth 2.0.[#] It is written and maintined by the OpenID Connect Working Group of the OpenID Foundation.

Whereas OAuth 2.0 is a framework for authorization, OpenID Connect is a protocol for authentication. Implementations of OpenID Connect provide a means of authenticating a user against a user store to provide an ID token which contains identity information about that user as well as an access token which contains information about what that user is allowed to do.

Identity Token

Access Token

How the tokens are used

Identity Server 4

Identity Server 4 is an implementation of OpenID Connect that's currently built to support .NET Core 3.1.

From our experience so far, it's pretty easy to configure and run. The difficult part is knowing what to configure and why, hence the content above about OAuth 2.0 and OpenID Connect.

OAuth 3.0