IdentityServer: What It Is and Where to Start

I have written a lot about Duende IdentityServer on this blog. This page puts those posts in a sensible reading order and answers the questions I get most often.

What Is IdentityServer?

IdentityServer is an OpenID Connect and OAuth 2.0 framework for ASP.NET Core. You host it in your own application, and it issues the tokens that your web apps, single-page apps, mobile apps and APIs use to sign users in and call APIs. Today it is a commercial product, Duende IdentityServer, from Duende Software.

IdentityServer4 was the free, open-source predecessor. Its support ended in December 2022, together with .NET Core 3.1, and the same authors carried the code forward as Duende IdentityServer. If you search for IdentityServer today, most of what you find about IdentityServer4 still applies to the concepts, but not to the current code and packages.

IdentityServer exposes a set of standard OpenID Connect and OAuth endpoints. Your client applications use them to sign users in and get tokens, and your APIs use them to get the keys they need to validate those tokens.

Why I Focus on IdentityServer

Customers began asking me about OpenID Connect and authentication, and honestly, the topic scared me. So around 2020 and 2021 I decided to learn it properly: I read the specifications, built workshops, and took apart how the pieces fit together. Duende IdentityServer has been my main OpenID Connect provider since then, for about five years now. I have also presented a Duende Software webinar on the topic, Demystifying Authentication in ASP.NET Core.

A fun fact: answering IdentityServer questions on Stack Overflow earned me the silver identityserver4 badge. The only other person who has it is one of the people who created IdentityServer.

What Goes Wrong in Practice

The same problems come up again and again, in questions from developers, in my workshops and in client projects:

• The templates feel like magic. Duende's templates get you running fast, but when something breaks you don't know which part does what. I prefer to build the setup from scratch once, so I understand every line I bring in.
• Scopes and resources get mixed up. IdentityResource, ApiResource and ApiScope control different things in different tokens. Mixing them up gives you tokens with the wrong claims or the wrong audience.
• Claims go missing in the client, not in IdentityServer. IdentityServer often issues the claim correctly, and then ASP.NET Core renames it or drops it on the way into the ClaimsPrincipal.
• Docker breaks the URLs. localhost means one thing in the browser and another inside a container. That gives you issuer mismatches, failed logins over HTTP because of SameSite cookies, and logout errors such as IDX10205.
• The Data Protection key ring is not persisted. Then a restart, a redeploy or a second instance invalidates cookies and breaks sign-in.
• Tokens end up in the browser. For single-page apps, I recommend the BFF pattern, so tokens stay on the server.

Most of these come down to the same thing: not knowing what goes over the wire. I use Fiddler a lot, and many of the posts below show the actual HTTP traffic.

Start Here

If OpenID Connect itself is new to you, read my OpenID Connect for Developers guide on tn-data.se first. IdentityServer is much easier to follow when you know what tokens, scopes, claims and flows are.

1. Set up IdentityServer

• Duende IdentityServer 7: A Complete Setup Guide for ASP.NET Core: builds a working IdentityServer from an empty ASP.NET Core project, step by step, so nothing is magic.
• IdentityServer - IdentityResource vs. ApiResource vs. ApiScope: the difference between the three resource types and how they shape your tokens.

2. Run IdentityServer in Docker

A four-part series that runs IdentityServer and a client in separate containers with Docker Compose, and fixes each problem as it shows up. Read it in order.

• Part 1: Adding Containers: the setup, and why localhost fails between containers.
• Part 2: Networking: service names, internal ports, MetadataAddress and the issuer mismatch.
• Part 3: HTTPS and SameSite: why login fails over HTTP and how to fix it with HTTPS.
• Part 4: Handle Logout: sign-out redirects, id_token_hint and the IDX10205 issuer error.

3. Connect your clients and APIs

These posts are about the ASP.NET Core side, where many IdentityServer problems actually show up.

• Debugging OpenID Connect Claim Problems in ASP.NET Core: what to check when a claim from IdentityServer never reaches your User object.
• Troubleshooting JwtBearer authentication issues in ASP.NET Core: 401 or 403 from your API, and how to find out why.
• Debugging JwtBearer Claim Problems in ASP.NET Core: missing or renamed claims in the access token on the API side.
• Demystifying OpenID Connect's State and Nonce Parameters in ASP.NET Core: what is inside these two parameters and what they protect against.
• Debugging cookie problems in ASP.NET Core: the cookies involved in an IdentityServer login, and why the browser sometimes rejects them.
• Pushed Authorization Requests (PAR) in ASP.NET Core 9: a safer way to start the login, using Duende IdentityServer.

4. Prepare for production

• Persisting the ASP.NET Core Data Protection Key Ring in Azure Key Vault: keep cookies and sign-in working across restarts and instances.
• Introducing the Data Protection API Key Ring Debugger: a small tool I wrote to look inside the key ring.

5. Keep tokens out of the browser (BFF)

• Implementing BFF Pattern in ASP.NET Core for SPAs: why tokens in a single-page app are a risk. Part 1 of a seven-part series.
• BFF in ASP.NET Core #2 - The BFF Pattern Explained: what a BFF is and what goes inside it.
• BFF in ASP.NET Core #7 - Introducing the Duende BFF Library: replacing a hand-built BFF with Duende's library.

Frequently Asked Questions

What is the difference between IdentityServer4 and Duende IdentityServer?

Duende IdentityServer is the continuation of IdentityServer4. IdentityServer4 was free and open source, but its support ended in December 2022 and it gets no more fixes. Duende IdentityServer is maintained and supports current .NET versions. If you still run IdentityServer4, plan an upgrade.

Is Duende IdentityServer free?

Duende IdentityServer is a commercial product, and there is a free Community Edition. For the latest licensing, see Duende's pricing page.

Should I use IdentityServer, Entra ID or Keycloak?

It depends on how much control you need and whether you want to run the identity server yourself. I compare them, and a few .NET alternatives, under Alternatives to IdentityServer below.

Can IdentityServer run in Docker?

Yes. The hard parts are networking and URLs: the browser and the containers reach IdentityServer through different addresses, and the issuer must still match. My IdentityServer in Docker Containers series walks through it step by step.

What is the difference between IdentityResource, ApiResource and ApiScope?

An IdentityResource controls which user claims go into the ID token. An ApiScope is a permission that a client can ask for in an access token. An ApiResource groups scopes under one API and sets the audience of the access token. I explain it in detail in IdentityResource vs. ApiResource vs. ApiScope.

Alternatives to IdentityServer

IdentityServer is not the only way to get an OpenID Connect provider for your .NET applications. These are some of the alternatives. Each has its own terms, so check its site for the current licensing.

Open.IdentityServer from Rock Solid Knowledge continues the IdentityServer4 codebase as a .NET SDK, with new features and security fixes added. It describes itself as an independent project, not affiliated with Duende Software or the original IdentityServer4 authors. See Open.IdentityServer.

OpenIddict is an OAuth 2.0 and OpenID Connect stack for .NET, with client, server and token validation support. You add it to your own .NET application. See the OpenIddict documentation.

Abblix OIDC Server from Abblix LLP is an OpenID Connect and OAuth 2.0 server for .NET that you deploy in your own environment. See Abblix.

Keycloak is an identity and access management server that you download and run yourself, outside your .NET code. You configure clients, users and flows in it instead of programming them. See Keycloak.

Microsoft Entra ID is Microsoft's cloud-based identity and access management service. Microsoft runs it, and you register and configure your applications in it. See What is Microsoft Entra?.

With IdentityServer, the login UI, the storage and the logic live in your own ASP.NET Core application, written in C#. I pick IdentityServer when a .NET team needs that control. The protocols are the same in all of them, which is why I think learning OpenID Connect first pays off.

Want to Go Further?

For the protocol itself, start with my free OpenID Connect for Developers guide on tn-data.se.

My Dometrain course Getting Started: OpenID Connect covers OAuth 2 and OpenID Connect at the protocol level: tokens, signing, scopes, claims and the flows. Everything IdentityServer does builds on that. For the ASP.NET Core side (the authentication middleware, cookies and authorization), see Getting Started: Authentication and Authorization in .NET.

If your team needs help with an IdentityServer setup, you can hire me.