Install Auth SDK

Installation

Install the Wristband Auth SDK from the NuGet repository:

dotnet add package Wristband.AspNet.Auth

NuGet\Install-Package Wristband.AspNet.Auth

Configure The SDK

Prerequisites

Before configuring the SDK, retrieve the following credentials:

WRISTBAND_APPLICATION_VANITY_DOMAIN
WRISTBAND_CLIENT_ID
WRISTBAND_CLIENT_SECRET

If you completed the Set Up a Wristband Application guide, you received these three values after your application was provisioned.

If you do not have them, retrieve them from the Wristband Dashboard by following the manual steps in that guide.

Register the Wristband Auth Service

Add the SDK's WristbandAuthService to Program.cs so your application can access it through dependency injection.

Call AddWristbandAuth() to inject the authentication service into your project's dependency container. You will use this service later to build your application's authentication endpoints.
Configure the AuthConfig options during registration with your application values.
📘
Disabling secure cookies in local development
AddWristbandAuth() configures secure login state cookies by default, which requires HTTPS. Most browsers allow secure cookies over HTTP for localhost, but strict browsers such as Safari block secure cookies over HTTP.
To prevent login failures on localhost:
1. Set options.DangerouslyDisableSecureCookies = true in your development configuration.
2. Re-enable secure cookies by setting this option to false before deploying to production.

// Program.cs

using Wristband.AspNet.Auth;

var builder = WebApplication.CreateBuilder(args);

// Register Wristband authentication service.
builder.Services.AddWristbandAuth(options =>
{
  options.ClientId = "<WRISTBAND_CLIENT_ID>";
  options.ClientSecret = "<WRISTBAND_CLIENT_SECRET>";
  options.WristbandApplicationVanityDomain = "<WRISTBAND_APPLICATION_VANITY_DOMAIN>";
});

//
// Other middleware and routes...
//

// Program.cs

using Wristband.AspNet.Auth;

var builder = WebApplication.CreateBuilder(args);

// Register Wristband authentication service.
builder.Services.AddWristbandAuth(options =>
{
  options.ClientId = "<WRISTBAND_CLIENT_ID>";
  options.ClientSecret = "<WRISTBAND_CLIENT_SECRET>";
  options.WristbandApplicationVanityDomain = "<WRISTBAND_APPLICATION_VANITY_DOMAIN>";
  options.DangerouslyDisableSecureCookies = true;
});

//
// Other middleware and routes...
//

Configure Session Cookie Authentication

Set up encrypted cookies to manage and validate user sessions. This integration builds on ASP.NET Core cookie authentication and adds Wristband session handling and security policies.

To enable zero-infrastructure session encryption, provide a strong secret key:

Length: Use at least 32 characters.
Randomness: Generate the key from a secure cryptographic source.
Tooling: Generate a secure key at https://securepassword.dev.

📘
Disabling secure session cookies in local development
Session cookies use a secure-only policy by default, which restricts transmission to HTTPS. Most browsers allow secure cookies over HTTP for localhost, but strict browsers such as Safari block secure cookies over HTTP.
To prevent login failures on localhost:

In AddCookie(), set options.Cookie.SecurePolicy to CookieSecurePolicy.SameAsRequest or CookieSecurePolicy.None.

In production, set the policy back to CookieSecurePolicy.Always to protect user sessions.

// Program.cs (continued)

using Microsoft.AspNetCore.Authentication.Cookies;
using Wristband.AspNet.Auth;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddWristbandAuth(options =>
{
  options.ClientId = "<WRISTBAND_CLIENT_ID>";
  options.ClientSecret = "<WRISTBAND_CLIENT_SECRET>";
  options.WristbandApplicationVanityDomain = "<WRISTBAND_APPLICATION_VANITY_DOMAIN>";
});

// ADD: Configure zero-infrastructure session encryption
builder.Services.AddInMemoryKeyDataProtection("<YOUR_SECRET_KEY_MIN_32_CHARS>");

// ADD: Configure encrypted cookie-based session authentication
builder.Services.AddAuthentication(CookieAuthenticationDefaults.AuthenticationScheme)
    .AddCookie(options => options.UseWristbandSessionConfig());

// ADD: Register Wristband authorization handler
builder.Services.AddWristbandAuthorizationHandler();

// ADD: Register Wristband authorization policies
builder.Services.AddAuthorization(options => options.AddWristbandDefaultPolicies());

//
// Other middleware and routes...
//

// Program.cs (continued)

using Microsoft.AspNetCore.Authentication.Cookies;
using Wristband.AspNet.Auth;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddWristbandAuth(options =>
{
  options.ClientId = "<WRISTBAND_CLIENT_ID>";
  options.ClientSecret = "<WRISTBAND_CLIENT_SECRET>";
  options.WristbandApplicationVanityDomain = "<WRISTBAND_APPLICATION_VANITY_DOMAIN>";
  options.DangerouslyDisableSecureCookies = true;
});

// ADD: Configure zero-infrastructure session encryption
builder.Services.AddInMemoryKeyDataProtection("<YOUR_SECRET_KEY_MIN_32_CHARS>");

// ADD: Configure cookie-based session authentication
builder.Services.AddAuthentication(CookieAuthenticationDefaults.AuthenticationScheme)
    .AddCookie(options =>
    {
        options.UseWristbandSessionConfig();
        options.Cookie.SecurePolicy = CookieSecurePolicy.SameAsRequest;
    })

// ADD: Register Wristband authorization handler
builder.Services.AddWristbandAuthorizationHandler();

// ADD: Add authorization policies
builder.Services.AddAuthorization(options => options.AddWristbandDefaultPolicies());

//
// Other middleware and routes...
//

What each component does:

Each middleware and configuration component has a specific role in your authentication pipeline:

AddInMemoryKeyDataProtection() configures session encryption using a shared secret, so sessions work across multiple servers without requiring a database or distributed cache such as Redis. Generate a secure secret key and store it in your environment configuration.
AddAuthentication(CookieAuthenticationDefaults.AuthenticationScheme) sets cookie authentication as the default framework mechanism, so session data is populated and available on every incoming request, including unprotected endpoints.
UseWristbandSessionConfig() applies Wristband's recommended defaults and security policies for session cookies.
AddWristbandAuthorizationHandler() registers the internal handler that validates incoming user sessions.
AddWristbandDefaultPolicies() registers the standard WristbandSession and WristbandJwt authorization policies, which you will use later to enforce authenticated access on your endpoints.

Add Authentication Middleware

Integrate the middleware pipeline to handle authentication and authorization. The middleware processes each request in this order:

Read and validate: Inspect and verify incoming session cookies.
Enforce policies: Evaluate and apply authorization policies on protected endpoints.
Commit changes: Save session changes back to the session cookie before completing the request.

📘
Middleware order matters

UseAuthentication() identifies who the user is.

UseAuthorization() checks what the identified user can access.

UseWristbandSessionMiddleware() manages session state for the authorized user.

// Program.cs (continued)

using Microsoft.AspNetCore.Authentication.Cookies;
using Wristband.AspNet.Auth;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddWristbandAuth(options =>
{
  options.ClientId = "<WRISTBAND_CLIENT_ID>";
  options.ClientSecret = "<WRISTBAND_CLIENT_SECRET>";
  options.WristbandApplicationVanityDomain = "<WRISTBAND_APPLICATION_VANITY_DOMAIN>";
});

builder.Services.AddAuthentication(CookieAuthenticationDefaults.AuthenticationScheme)
    .AddCookie(options => options.UseWristbandSessionConfig());

builder.Services.AddWristbandAuthorizationHandler();

builder.Services.AddAuthorization(options => options.AddWristbandDefaultPolicies());

var app = builder.Build();

// ADD: Reads session cookie and populates HttpContext.User
app.UseAuthentication();

// ADD: Enforces authorization policies on protected endpoints
app.UseAuthorization();

// ADD: Automatically saves session changed to the session cookie
app.UseWristbandSessionMiddleware();

//
// Your API routes will go here...
//

app.Run();

What each middleware does:

UseAuthentication() - Reads the session cookie on each request and populates HttpContext.User with session data.
UseAuthorization() - Enforces authorization policies, such as session validation, on protected endpoints.
UseWristbandSessionMiddleware() - Automatically saves session changes to the encrypted cookie after your endpoint completes.