Install Auth SDK

After setting up ASP.NET Core, install and configure the Wristband ASP.NET SDK in your C# server.

Installation

Install the Wristband Auth SDK from the NuGet repository:

dotnet add package Wristband.AspNet.Auth

NuGet\Install-Package Wristband.AspNet.Auth

Configuration

There are a couple ways to configure your SDK to enable proper communication between your ASP.NET web application and Wristband.

For detailed SDK configuration options, view our GitHub documentation for aspnet-auth configuration options.

📘

Mapping Configuration Values

Regarding configuration for testing your auth integration:

• The LoginUrl and RedirectUri are the URL values you provided when creating your Wristband Application and OAuth2 Client, respectively, in the Wristband Dashboard.
• The ClientId, ClientSecret, and WristbandApplicationDomain values were presented to you after you created your Wristband Application and OAuth2 Client in the Wristband Dashboard.
• For Production environments, ensure that DangerouslyDisableSecureCookies is set to false.
• LoginStateSecret will be used to secure cookie contents for login requests to Wristband. You can generate a secret by running:
  bash

  openssl rand -base64 32
  

Option 1: Configuring JSON (Recommended)

JSON configuration provides a clean separation of configuration from code, allowing for environment-specific settings, improved security through secret management, and the ability to modify application behavior without recompilation.

Non-secret Values

Add the following configuration section to your appsettings.json file, replacing all placeholder values with your own:

"WristbandAuthConfig": {
  "ClientId": "--some-identifier--",
  "LoginUrl": "https://example.com/auth/login",
  "RedirectUri": "https://example.com/auth/callback",
  "Scopes": ["openid", "offline_access", "email", "roles", "profile"],
  "UseTenantSubdomains": "false",
  "WristbandApplicationDomain": "sometest-account.us.wristband.dev"
},

"WristbandAuthConfig": {
  "ClientId": "--some-identifier--",
  "LoginUrl": "https://{tenant_domain}.example.com/auth/login",
  "RedirectUri": "https://{tenant_domain}.example.com/auth/callback",
  "RootDomain": "example.com",
  "Scopes": ["openid", "offline_access", "email", "roles", "profile"],
  "UseTenantSubdomains": "true",
  "WristbandApplicationDomain": "sometest-parent.us.wristband.dev"
},

Secret Values

To configure the Client Secret and LoginStateSecret that the SDK relies on in a secure manner during local testing, you can use .NET User Secrets:

🚧

User secrets are for development only

For production, use environment variables or your platform's secure configuration management system.

1. Initialize user secrets in your project:

   bash

   dotnet user-secrets init
   

   This will add a UserSecretsId to your .csproj file that looks like this:

   XML

   <PropertyGroup>
     <UserSecretsId>a-randomly-generated-guid</UserSecretsId>
   </PropertyGroup>
   

2. Set your secrets using the CLI:

   bash

   dotnet user-secrets set "WristbandAuthConfig:ClientSecret" "your-client-secret"  
   dotnet user-secrets set "WristbandAuthConfig:LoginStateSecret" "your-login-state-secret"
   

   Alternatively, you can manage secrets through Visual Studio by right-clicking your project and selecting "Manage User Secrets". Either method will create/update a secrets.json file. Then, add the following to secrets.json:

   JSON

   {  
     "WristbandAuthConfig": {  
       "ClientSecret": "your-client-secret",  
       "LoginStateSecret": "your-login-state-secret"  
     }  
   }
   

3. During development, the secrets will automatically be loaded when you create your WebApplication builder for the following methods:

   • A secrets.json in development, or,

   • Environment variables prefixed with ASPNETCORE_

     C#

     // Program.cs
     
     var builder = WebApplication.CreateBuilder(args);
     

     You can also explicitly load secrets through the User Secrets configuration provider:

     C#

     builder.Configuration.AddUserSecrets<Program>();
     

     ...or you can explicitly load from a JSON file:

     C#

     builder.Configuration.AddJsonFile("mysecrets.json", optional: true);
     

     In production, another alternative to environment variables is a secure configuration management system:

     C#

     builder.Configuration.AddAzureKeyVault(
         new Uri("https://your-vault.vault.azure.net/"),
         new DefaultAzureCredential());
     

4. Enable authentication middleware, and add the SDK's WristbandAuthenticationService in your Program.cs file.

   C#

   // Program.cs
   
   using Wristband.AspNet.Auth;
   
   var builder = WebApplication.CreateBuilder(args);
   
   // Register Wristband authentication configuration and inject WristbandAuthService.
   builder.Services.AddWristbandAuth(builder.Configuration);
   
   //
   // Other middleware and routes...
   //
   
   ...
   

Option 2: Direct Configuration

You can also configure secrets directly in your code, which is helpful during development, testing, or when configuration values need to be calculated dynamically at runtime.

// Program.cs

builder.Services.AddWristbandAuth(options =>
{
  options.ClientId = "direct-client";
  options.ClientSecret = "direct-secret";
  options.LoginStateSecret = "this-is-a-secret-that-is-at-least-32-chars";
  options.LoginUrl = "https://login.url";
  options.RedirectUri = "https://redirect.uri";
  options.WristbandApplicationDomain = "wristband.domain";
});