Install Auth SDK
Learn how to configure the Wristband SDK for your Express application.
After setting up Express, you'll need to install and configure the Wristband ExpressJS SDK.
Installation
Install the Wristband Auth SDK using your preferred package manager CLI:
npm install @wristband/express-auth
yarn add @wristband/express-auth
pnpm add @wristband/express-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:
-
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.
-
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.
-
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.
-
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.
-
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:
openssl rand -base64 32
Configure The SDK
Create an instance of WristbandAuth
in the source root directory of your Express project (e.g.src/wristband-auth.ts
). Update the AuthConfig
properties with the values mentioned in the above sections.
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
totrue
. However, in production environmentsdangerouslyDisableSecureCookies
should always be set tofalse
.
import { createWristbandAuth } from '@wristband/express-auth';
import { AuthConfig } from './types';
const authConfig: AuthConfig = {
clientId: '<your-client-id>',
clientSecret: '<your-client-secret>',
dangerouslyDisableSecureCookies: true,
loginStateSecret: '<your-login-state-secret>',
loginUrl: '<your-login-url>',
redirectUri: '<your-client-redirect-uri>',
scopes: ['openid', 'offline_access', 'email', 'profile', 'roles'],
wristbandApplicationDomain: '<your-application-vanity-domain>',
useTenantSubdomains: false,
useCustomDomains: false,
};
export const wristbandAuth = createWristbandAuth(authConfig);
const { createWristbandAuth } = require('@wristband/express-auth');
const authConfig = {
clientId: 'your-client-id',
clientSecret: 'your-client-secret',
dangerouslyDisableSecureCookies: true,
loginStateSecret: 'your-login-state-secret',
loginUrl: 'https://your-login-url',
redirectUri: 'https://your-redirect-uri',
scopes: ['openid', 'offline_access', 'email', 'profile', 'roles'],
wristbandApplicationDomain: 'your-wristband-application-domain',
useTenantSubdomains: false,
useCustomDomains: false,
};
export const wristbandAuth = createWristbandAuth(authConfig);
Updated 7 days ago
Next, you'll use your configured Wristband Auth instance to create the necessary authentication endpoints in your Express server.