DEV Community

Abdullah D.
Abdullah D. Subscriber

Posted on

Secure Your .NET 8 APIs in Minutes with OpenIddict: A Minimalist's Guide

#dotnetcore #identity #openiddict #oauth

API security is non-negotiable, but implementing OAuth 2.0 and OpenID Connect can often feel like a monumental task, bogged down by complex configurations and boilerplate code. What if you could set up a robust, spec-compliant OIDC server for your .NET API in just a few minutes, with code that fits on a single screen?

That's exactly what I set out to do. I've created a minimal, self-contained OpenIddict server that provides a rock-solid foundation for token-based authentication, and I've published the complete source code on GitHub.

This guide will walk you through how it works and how you can get it running in less time than it takes to brew your morning coffee.

You can find the full, ready-to-run project here.

Why OpenIddict? The Power of "No Magic"

There are many identity solutions for .NET, but OpenIddict stands out for its "no magic" philosophy. It's a low-level, highly configurable framework that gives you full control over the authentication flow. Instead of hiding the implementation behind layers of abstraction, it provides the essential building blocks, allowing you to build a server that is both powerful and transparent.

This project embraces that philosophy to create an API-first server with key features:

  • OIDC & OAuth 2.0 Compliant: No shortcuts, just standard-based security.
  • Essential Flows Included: Supports Password, Client Credentials, and Refresh Token grants out-of-the-box.
  • Minimal & Self-Contained: The entire configuration is in Program.cs. No hunting through files to understand what's going on.
  • Instant Testing: Comes with a pre-seeded client and admin user.

The Core Configuration: Less Code, More Security

The heart of the server is in the Program.cs file. By chaining a few configuration methods, we can set up the entire OpenID Connect server.

Here's a look at the core AddOpenIddict() configuration:

builder.Services.AddOpenIddict()
    .AddCore(/*...EF Core setup...*/)
    .AddServer(options =>
    {
        // 1. Set the endpoint URIs
        options.SetTokenEndpointUris("connect/token")
               .SetUserinfoEndpointUris("connect/userinfo");

        // 2. Enable the grant types you need
        options.AllowPasswordFlow()
               .AllowRefreshTokenFlow()
               .AllowClientCredentialsFlow();

        // 3. Explicitly enable the endpoints
        options.AllowUserinfoEndpoint()
               .AllowIntrospectionEndpoint()
               .AllowRevocationEndpoint();

        // 4. Configure certificates and ASP.NET Core integration
        options.AddDevelopmentEncryptionCertificate()
               .AddDevelopmentSigningCertificate();

        options.UseAspNetCore()
               .EnableTokenEndpointPassthrough();
    })
    .AddValidation(/*...JWT validation setup...*/);
Enter fullscreen mode Exit fullscreen mode

In this small block of code, we've configured our endpoints, enabled specific OAuth 2.0 flows, registered scopes, and set up our development certificates. It's clean, readable, and incredibly efficient.

Get it Running in Under a Minute

Getting the server running on your machine is a simple two-step process.

  1. Restore Dependencies: 
   dotnet restore
Enter fullscreen mode Exit fullscreen mode
  1. Run the Server: 
   dotnet run
Enter fullscreen mode Exit fullscreen mode

That's it! The first time you run it, an openiddict.db SQLite file is created, and the database is automatically seeded with a test client (postman) and an admin user (admin@test.com). No manual database setup required.

Testing Your Secure Endpoints

To make testing easy, the project includes an api.http file. If you use Visual Studio Code with the REST Client extension, you can immediately start sending requests.

Here's how you would request a token using the password flow:

# From api.http

POST http://localhost:5000/connect/token
Content-Type: application/x-www-form-urlencoded

grant_type=password
&client_id=postman
&client_secret=postman-secret
&username=admin@test.com
&password=AdminPassword123!
&scope=openid profile api
Enter fullscreen mode Exit fullscreen mode

Just click "Send Request," and you'll get back a live access token and refresh token.

Conclusion: Your Foundation for Secure APIs

This minimal server is the perfect starting point. It solves the immediate, and often complex, problem of setting up a secure token service. From here, you can easily extend it to support more flows, integrate it with a frontend application, or deploy it as a central authentication authority for your microservices.

Building secure APIs doesn't have to be a headache. With the right tools and a clean, minimal approach, you can create a robust and transparent authentication system.

Check out the repository on GitHub, clone the code, and see for yourself!

Top comments (0)