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 you can configure the SDK, you'll need to make sure you have the following values:

• WRISTBAND_APPLICATION_VANITY_DOMAIN
• WRISTBAND_CLIENT_ID
• WRISTBAND_CLIENT_SECRET

If you went through the Set Up a Wristband Application guide, you should have been presented with these three values after the application was provisioned. If you don't have the above values on hand, you can retrieve them from the Wristband dashboard by following the steps in this guide.

Register the Wristband Auth Service

Register the SDK's WristbandAuthService in your Program.cs file by calling the AddWristbandAuth() method. This service is made available to your application via dependency injection and will be used to implement your application's authentication endpoints later in the quickstart guide. When calling AddWristabndAuth() make sure to update the AuthConfig options with the values for your application.

⚙️

Disabling Secure Cookies in Local Development

By default, AddWristbandAuth() creates secure cookies (for tracking login state), meaning they are only sent over HTTPS connections. Most browsers make an exception for localhost and allow secure cookies to be sent over HTTP (e.g., http://localhost). However, some browsers, such as Safari, enforce stricter rules and never send secure cookies over HTTP, even for localhost.

If you need to disable the secure cookies for local development, set options.DangerouslyDisableSecureCookies = true. However, be sure to re-enable secure cookies 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

Next, configure your application to store and validate user sessions using encrypted cookies. This builds on ASP.NET Core's built-in encrypted cookie authentication with Wristband-specific session handling and security policies.

To take advantage of zero-infrastructure session encryption, you'll need to provide a secret key (at least 32 characters long). You can generate a secure secret using 1Password's password generator.

⚙️

Disabling Secure Session Cookies in Local Development

By default, session cookies are marked as secure, meaning they are only sent over HTTPS connections. Most browsers make an exception for localhost and allow secure cookies to be sent over HTTP (e.g., http://localhost). However, some browsers, such as Safari, enforce stricter rules and never send secure cookies over HTTP, even for localhost.

If you need to disable the secure flag for local development, set options.Cookie.SecurePolicy = CookieSecurePolicy.SameAsRequest (or CookieSecurePolicy.None) in AddCookie(). However, be sure to restore CookieSecurePolicy.Always in production to protect session data.

// 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:

• AddInMemoryKeyDataProtection() - Configures session encryption using a shared secret. This enables sessions to work across multiple servers without requiring Redis or databases. Generate a secure secret and store it in your environment configuration.
• AddAuthentication(CookieAuthenticationDefaults.AuthenticationScheme) - Sets cookie authentication as the default, making session data available on every request (including unprotected endpoints).
• UseWristbandSessionConfig() - Applies Wristband's recommended defaults for session cookies.
• AddWristbandAuthorizationHandler() - Registers the handler that validates sessions.
• AddWristbandDefaultPolicies() - Registers authorization policies ("WristbandSession" and "WristbandJwt") that you'll use later to enforce authenticated access to your endpoints.

Add Authentication Middleware

Add the middleware pipeline that processes authentication and authorization on every request. The middleware runs in order: first reading and validating session cookies, then enforcing authorization policies on protected endpoints, and finally saving any session updates back to the session cookie:

⚠️

Middleware Order Matters

Always call UseAuthentication() before UseAuthorization(), and both before UseWristbandSessionMiddleware().

// 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.