Install Auth SDK

After setting up ASP.NET Core, you'll need to install and configure the Wristband ASP.NET SDK.

Installation

Install the Wristband Auth SDK from the NuGet repository:

dotnet add package Wristband.AspNet.Auth

NuGet\Install-Package Wristband.AspNet.Auth

Configuration

Prerequisites

Before you can configure the Wristband SDK, you'll need to make sure you have the following values that were generated or specified when you set up your Wristband application:

1. WristbandApplicationDomain - This is the vanity domain of your application. To find this value, select your application from the Dashboard Home Page. On the "Application Settings" page, you'll see the "Application Vanity Domain" field in the top info box.

   
   

2. LoginUrl - This is the login URL that was specified when your application was created. To find this value, select your application from the Dashboard Home Page. On the "Application Settings" page, scroll down until you see the "Login URL" field.

   
   

3. ClientId - This is the ID of the OAuth2 Client that was created as part of the application setup process. To find this value, select your application from the Dashboard Home Page. In the left navigation bar, select "OAuth2 Clients" and then select the client you created earlier. The client ID will be present in the top info box.

   
   

4. ClientSecret - This is the secret of the OAuth2 Client that was created as part of the application setup process. The client's secret is only shown when the client is first created. If you don't remember the secret that was initially generated for the client, you can rotate the secret to create a new one. To rotate the client's secret, select "OAuth2 Clients" from the left navigation bar, and then select the client whose secret you'd like to rotate. On the client page, scroll down to the "Client Secret Settings" section and then select the "Rotate" button. Your client's new secret will be presented in a modal.

   
   

5. RedirectUri - This is the redirect URI that was specified when you created your OAuth2 Client. To find this value, select your application from the Dashboard Home Page. In the left navigation bar, select "OAuth2 Clients" and then select the client you created earlier. On the client page, scroll down until you see the "Authorization Callback URLs." You can use any of the client's authorization callback URLs as the RedirectUri value.

   
   

Generate a Login State Secret

The Wristband SDK requires the creation of a login state secret, which it will use to encrypt the contents of the login state cookie. The login state cookie is used by the Wristband SDK to persist state between the login and callback endpoints of your application. You can generate a login state secret by running the following command:

bash

openssl rand -base64 32

Configure The SDK

There are a couple of ways to configure the Wristband SDK. For detailed SDK configuration options, view our GitHub documentation for aspnet-auth configuration options.

ℹ️

Disabling Secure Cookies

When testing locally, if your application isn't utilizing HTTPS, you'll need to update the Wristband SDK to not use secure cookies by setting DangerouslyDisableSecureCookies to true. However, in production environments DangerouslyDisableSecureCookies should always be set to false.

Option 1: JSON Configuration (Recommended)

JSON configuration provides a clean separation of configuration from code, allowing for environment-specific settings and improved security through secret management.

Non-secret Values

First, to configure the non-secret values, add the following configuration section to your appsettings.json file, replacing all placeholder values with your own:

"WristbandAuthConfig": {
  "ClientId": "<your-client-id>",
  "DangerouslyDisableSecureCookies": "true",
  "LoginUrl": "<your-application-login-url>",
  "RedirectUri": "<your-client-redirect-uri>",
  "Scopes": ["openid", "offline_access", "email", "roles", "profile"],
  "UseTenantSubdomains": "false",
  "WristbandApplicationDomain": "<your-application-vanity-domain>"
},

"WristbandAuthConfig": {
  "ClientId": "<your-client-id>",
  "DangerouslyDisableSecureCookies": "true",
  "LoginUrl": "<your-login-url>",
  "RedirectUri": "<your-client-redirect-uri>",
  "RootDomain": "<your-apex-domain>",
  "Scopes": ["openid", "offline_access", "email", "roles", "profile"],
  "UseTenantSubdomains": "true",
  "WristbandApplicationDomain": "<your-application-vanity-domain>"
},

Secret Values

Next, to configure the ClientSecret and LoginStateSecret, 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 or update a secrets.json file with the following content:

   JSON

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

3. During development, when you create your WebApplication builder, the secrets will be resolved automatically from the secrets.json file 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 specify a different JSON file to load the secrets from:

   C#

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

   In production, instead of storing secrets in environment variables, a secure secret management system such as Azure Key Vault can be used:

   C#

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

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

Instead of using JSON configurations and environment variables, you can also configure the Wristband SDK directly in your code, which can be helpful during development.

// Program.cs

builder.Services.AddWristbandAuth(options =>
{
  options.ClientId = "<your-client-id>";
  options.ClientSecret = "<your-client-secret>";
  options.DangerouslyDisableSecureCookies: true,
  options.LoginStateSecret = "<your-login-state-secret>";
  options.LoginUrl = "<your-login-url>";
  options.RedirectUri = "<your-client-redirect-uri>";
  options.WristbandApplicationDomain = "<your-application-vanity-domain>";
});