When to Opt for a Backend Server Integration

For web applications, the recommended approach for integrating with Wristband is to use a backend server. Note that a backend server, in this case, could be a traditional web application server, serverless functions, or a Backend For Frontend (BFF). In general, the only time you'd not want to integrate with Wristband using a backend server is if your application is a pure single-page application that operates without any backend.

The primary advantage of using a backend server to integrate with Wristband is the enhanced security it offers for storing access and refresh tokens. In this integration pattern, tokens are encrypted and stored in an HTTP-only session cookie or a server-side datastore like Redis. This approach prevents browser-based attacks, such as cross-site scripting (XSS), from accessing or stealing the user's tokens.

Architecture at a Glance

For the Backend Server Integration pattern, a server hosts all the endpoints needed to interact with Wristand. Specifically, the backend server must implement the following four endpoints to authenticate users with Wristband: a login endpoint, a callback endpoint, a logout endpoint, and a session endpoint.

Login Endpoint

The login endpoint is responsible for initializing the application's user authentication flow. This endpoint constructs an OIDC authorization URL, which includes necessary parameters like the client ID, redirect URI, and the requested scopes, and then redirects to Wristband's authorization endpoint. Wristband then redirects the user to its hosted login pages.

Callback Endpoint

After successful authentication, Wristband redirects the user back to the callback endpoint on the backend server, passing an authorization code. The backend server captures the authorization code from the callback URL and exchanges it for an access token and refresh token by making a request to the Wristband token endpoint. Once the tokens are received, the backend server then stores the tokens, typically in a client-side cookie session or in a server-side session store. The callback endpoint then redirects back to the application, setting the session cookie in the redirect response.

Session Endpoint

The client-side Javascript must initialize the user's session by requesting session data from the server's session endpoint. The session endpoint relies on the presence of a session cookie to extract the user's session information. If client-side cookies are used, then all the session information can be retrieved directly from the cookie. Otherwise, if server-side cookies are used, then the session ID is pulled from the session cookie, and it's used to look up the session data from a server-side datastore.

Logout Endpoint

The logout endpoint handles deleting the user's session cookie and revoking any associated tokens. Also, the application's logout endpoint must redirect to Wristband's logout endpoint to ensure that Wristband's auth session is also deleted. Once Wristband's logout endpoint completes the request, it will then redirect back to the user's application.