OpenIddict samples map every OAuth flow to a named project

One project per flow, and the naming is Star Wars

The repository contains samples demonstrating how to use OpenIddict with the different OAuth 2.0 and OpenID Connect flows, and the way the samples are organised is the first thing to understand about them.

Each sample is a complete, runnable .NET project named after a Star Wars planet, and the name is only the label; what matters is the flow each one demonstrates. Aridka is a client credentials demo using mTLS client authentication, with a .NET console acting as the client. Balosar is an authorization code flow demo with a Blazor WASM application as the client. Contruum is a conformance tests project built on Razor Pages with two hardcoded user identities, meant to be used with the OIDC certification suite. Dantooine is a backend-for-frontend Blazor WASM application hosted in ASP.NET Core with Microsoft YARP for the downstream API.

The list continues across the flows. Geonosis is a Blazor Web application in InteractiveAuto mode, a backend-for-frontend with YARP and a token exchange flow to call a downstream API. Hollastin is a resource owner password credentials demo with a .NET console using mTLS token binding as the client. Imynusoph is the refresh token grant. Matty is the device authorization flow. Mimban is an authorization code flow on minimal APIs with GitHub delegation for user authentication. Velusia is an authorization code flow with an ASP.NET Core application as the client. Weytta adds Integrated Windows Authentication support. Zirku is the most comprehensive of the set, using minimal APIs with two hardcoded user identities, a console client using mTLS token binding, a SPA acting as a client, and two API projects, one using introspection and one using local validation.

That last pairing is the one to study if you are choosing between two ways of validating a token in a downstream service.

Older stacks are still represented

The catalogue is not limited to current .NET, and the two legacy groups are the part most people skim past.

The OWIN and ASP.NET 4.8 group has three samples. Fornax is an authorization code flow demo using ASP.NET Web Forms 4.8 and OWIN with Katana, with a .NET console as the client. Mortis is an authorization code flow demo using ASP.NET MVC 5.2 and ASP.NET Web API 2.2, with an ASP.NET MVC 5.2 application as the client. Kalarba is a resource owner password credentials demo using OWIN with Katana, ASP.NET Web API 2.2 and the OpenIddict degraded mode.

That last one deserves a note, because the degraded mode is a specific configuration of OpenIddict rather than a flow, and having a sample that uses it means there is a working reference for what that mode looks like in an OWIN application rather than a snippet.

The plain .NET group is separate from the ASP.NET Core group and contains Sorgan, which covers console, Windows Forms, Windows Presentation Foundation and Blazor Hybrid clients using GitHub for user authentication. That is a desktop client matrix in one project, which is unusual and useful if you are shipping a native application rather than a web one.

The three external samples listed in the README extend the pattern outside the organisation. There are Angular and Blazor samples by Damien Bowden, a MAUI client sandbox for iOS, Mac Catalyst and WinUI 3 by Kévin Chalet, and an OIDC session management sample by Graham Esau.

The pattern across all of them is the same. Each sample is one flow, one stack, one client type. That is a deliberate design, and it is why the repository reads as a reference index rather than a tutorial.

The certification story explains the Contruum sample

The Certification section of the README is the most opinionated part of the document, and it explains why Contruum exists in the shape it does.

The claim is that, unlike many other identity providers, OpenIddict is not a turnkey solution but a framework that requires writing custom code to be operational, typically at least an authorization controller, which makes it a poor candidate for the certification program. The reasoning continues: while a reference implementation could be submitted as-is, that would not guarantee that implementations deployed by OpenIddict users would be standard-compliant.

So the recommendation is that developers are encouraged to execute the conformance tests against their own deployment once they have implemented their own logic. The Contruum sample exists for that purpose, specially designed to be used with the OpenID Connect Provider Certification tool and to demonstrate that OpenIddict can be used in a certified implementation. To make the certification tests run as fast as possible, that sample does not include any membership or consent feature, and two hardcoded identities are proposed for the tests that require switching between identities.

That is a design decision with a clear purpose. A certification run is a long sequence of protocol exchanges, and a sample with real user management in it would spend most of the run on state that the certification tool does not care about.

For an adopter, the same logic applies to the other samples. They are demonstrations of protocol flows, and the identity handling in them is deliberately minimal, which is exactly what makes them short enough to read in an afternoon.

Security, support and who maintains the framework

The project publishes three policies in the README, and they are short enough to be worth reading in full.

Security issues and bugs should be reported privately by email to [email protected], with a stated response time of within 24 hours, and a note to follow up by email if no response arrives so the original message is not lost.

The support policy is delegated to a separate page at openiddict.com/support, and the repository points there rather than describing support options inline.

The contributors section is the one that names people. OpenIddict is actively maintained by Kévin Chalet, and the README states that contributions are welcome and may be submitted through pull requests. That is a single-maintainer statement in a project with a large sample catalogue, which tells you something about how decisions get made and where to raise an issue about a sample.

The licence section is straightforward. The project is licensed under the Apache License, described as meaning you can use, modify and distribute it freely, with a link to the Apache 2.0 text.

The repository layout supports the picture of a large, actively worked set of samples. There is an OpenIddict.Samples.slnx solution file, a samples directory, a Directory.Build.props and Directory.Build.targets for shared build settings, a Directory.Packages.props for central package version management, a NuGet.config, a global.json, a build.sh and build.cmd, and an eng directory for the build engineering. The default branch is dev, which is the branch a contributor works against, and the projects are built with a shared property and package management setup rather than each sample standing alone.

Where these samples stop helping

The samples cover the flows, and they do it in a way that is legible. What they deliberately do not do is stand in for a deployment.

The first limit is the one the README states. OpenIddict requires custom code to be operational, so what a sample gives you is the wiring for one flow, not an identity provider. Anyone expecting to configure their way to a compliant server from a sample is reading the wrong document.

The second is the identity handling. Contruum has two hardcoded user identities, and Zirku has two hardcoded user identities. The other samples lean on external identity providers for user authentication, GitHub in the cases of Mimban, Weytta and Sorgan. That is a sensible way to keep a sample short, and it means none of them demonstrates a user store, a registration flow or a password reset, which are exactly the parts a real deployment has to get right and none of which the protocol is about.

The third is the security surface. The samples are demonstrations, and the README asks for security issues to be reported privately, which implies the sample configurations are not hardened for anything but a local run. A deployment that takes a sample as its starting point inherits its token lifetimes, its client registration and its redirect URI settings, and the parts of a security review that matter most are the parts no sample covers.

There is a fourth, smaller limitation. Several samples demonstrate flows that are deprecated or restricted in practice, most obviously the resource owner password credentials flow in Hollastin and Kalarba. The samples exist to show that OpenIddict supports them, and reading them as a recommendation for a new system would be a mistake, since the flow itself is the reason many providers avoid it.

Editorial conclusion

The OpenIddict samples suit a developer who has to implement an authorization server and needs a working reference for one specific flow rather than for OpenID Connect in general, since the catalogue is organised exactly that way. It is the wrong starting point for anyone who wants a ready-made identity provider, because the README states plainly that OpenIddict is a framework requiring custom code and not a turnkey solution, and it is the wrong place to look for a production deployment guide. Before you base anything on a sample, read the security and support policies the README points at, note that the default branch is dev, and remember that the sample you copy is starting code rather than a reference implementation of the specification.

Frequently asked questions

Official sources

1. Issues
2. License: Apache-2.0
3. openiddict/openiddict-samples on GitHub
4. Project website
5. README