ASP.NET Core web application

Add OneiD to a .NET application with Microsoft.AspNetCore.Authentication.OpenIdConnect, step by step.

View as Markdown

This quickstart adds OneiD to a server web application with Microsoft.AspNetCore.Authentication.OpenIdConnect. Every file is complete and runs as it is.

Tip Using an AI coding agent? Give it this page as Markdown (add .md to the address) together with the Connector specification. See Build with AI coding agents.

Before you start

  • A OneiD address, for example https://YOUR_ONEID. The code below uses the demonstration instance https://auth.oltinid.com; replace it with your own.
  • A client registered for this application (step 1). The code uses the client ID quickstart; replace it with yours.
  • A user who can sign in to your OneiD. For the demonstration instance, ask for a demo account.

1. Register the application

Ask your OneiD administrator to register a client with these settings, or register it yourself in the admin console. See Register an application.

Setting Value
Client type public (no secret)
Grant types authorization_code (add refresh_token if you request offline_access)
Redirect URI https://localhost:3000/callback
Post-logout redirect URI https://localhost:3000/signout-callback-oidc
Allowed scopes openid profile email

2. Install

dotnet add package Microsoft.AspNetCore.Authentication.OpenIdConnect

3. Add the code

Program.cs

using Microsoft.AspNetCore.Authentication;
using Microsoft.AspNetCore.Authentication.Cookies;
using Microsoft.AspNetCore.Authentication.OpenIdConnect;

var builder = WebApplication.CreateBuilder(args);

builder.Services
    .AddAuthentication(options =>
    {
        options.DefaultScheme = CookieAuthenticationDefaults.AuthenticationScheme;
        options.DefaultChallengeScheme = OpenIdConnectDefaults.AuthenticationScheme;
    })
    .AddCookie()
    .AddOpenIdConnect(options =>
    {
        options.Authority = "https://auth.oltinid.com";
        options.ClientId = "quickstart";
        options.ResponseType = "code";      // authorization code flow; PKCE is on by default
        options.CallbackPath = "/callback";
        options.Scope.Add("email");         // openid and profile are requested by default
        options.SaveTokens = true;
        options.MapInboundClaims = false;   // keep the claim names that OneiD sends
        options.TokenValidationParameters.NameClaimType = "name";
        options.TokenValidationParameters.RoleClaimType = "role";
    });

builder.Services.AddAuthorization();

var app = builder.Build();
app.UseAuthentication();
app.UseAuthorization();

app.MapGet("/", (HttpContext context) =>
    Results.Content(
        context.User.Identity?.IsAuthenticated == true
            ? $"Hello, {context.User.Identity.Name}. <a href=\"/logout\">Sign out</a>"
            : "<a href=\"/login\">Sign in with OneiD</a>",
        "text/html"));

app.MapGet("/login", () =>
    Results.Challenge(new AuthenticationProperties { RedirectUri = "/" }));

// Ends the session in this application and in OneiD.
app.MapGet("/logout", () =>
    Results.SignOut(
        new AuthenticationProperties { RedirectUri = "/" },
        [CookieAuthenticationDefaults.AuthenticationScheme, OpenIdConnectDefaults.AuthenticationScheme]));

// HTTPS: the sign-in cookies of this library need it. Run `dotnet dev-certs https --trust` once.
app.Run("https://localhost:3000");

4. Run it

Run: dotnet run. The example listens on https://localhost:3000.

The example uses a public client so that it runs without a secret. For your own application, use a confidential client and set options.ClientSecret from a secret store.

Checkpoint Open https://localhost:3000 and select Sign in with OneiD. After you sign in, the page shows Hello, followed by the user’s name, and a Sign out link.

Common issues

  • OneiD shows an error page about the redirect address (invalid_request). The redirect URI the code sends is not registered on the client exactly as written. Register it, including scheme and port.
  • invalid_grant from the token endpoint. The code was used before or expired. Start the sign-in again; do not reload the callback page.
  • Correlation failed. The application runs on plain http. Run it on https, as the example does.
  • More errors and fixes: Errors and troubleshooting.

Learn more