How User Authentication Works

For user authentication, Wristband utilizes the OIDC Authorization Code Flow with PKCE (Proof Key for Code Exchange). As part of this flow, Wristband provides the following endpoints:

• Authorize Endpoint: Your application redirects the browser to this endpoint to initiate user authentication. After validating the authorization request, Wristband presents the user with a login page configured according to your application's settings. Once the user successfully authenticates, Wristband redirects them to your application's registered Callback Endpoint with an authorization code.

  For more information, see the Authorize API documentation.

• Token Endpoint: After the user successfully authenticates, Wristband redirects them to your application's Callback Endpoint with an authorization code appended as the code query parameter. Your application then calls the Wristband Token Endpoint to exchange the authorization code for an access token and an ID token. If the authorization request included the offline_access scope, Wristband also returns a refresh token.

  For more information, see the Token API documentation.

• UserInfo Endpoint: After obtaining an access token from the Token Endpoint, your application can call the Wristband UserInfo Endpoint, passing the access token as a bearer token in the Authorization header. The response contains claims about the authenticated user, with the specific claims determined by the scopes included in the authorization request.

  User Claims are not Included in the ID Token

  According to the OpenID Connect (OIDC) specification, when an access token is issued, claims requested through the profile, email, address, and phone scopes are returned by the UserInfo Endpoint rather than the ID token.

  Wristband always returns an access token from the Token Endpoint. Therefore, claims requested through these scopes are returned by the UserInfo Endpoint and are not included in the ID token by default.

  For more information, see the UserInfo API documentation.

The following diagram illustrates the high-level interactions between your application and Wristband endpoints during a user authentication flow.

sequenceDiagram
    actor User
    participant Browser as User's Browser
    participant App as Your Application
    participant Wristband as Wristband

    User->>App: Clicks the log in button
    App->>Browser: Redirects to Authorize Endpoint
    Browser->>Wristband: Sends authorization request
    Wristband->>Wristband: Authenticates the user
    Wristband-->>Browser: Redirects to Callback Endpoint with authorization code
    Browser->>App: Delivers authorization code to callback
    App->>Wristband: Exchanges authorization code at Token Endpoint
    Wristband-->>App: Returns access token, ID token, and optional refresh token
    App->>Wristband: Calls UserInfo Endpoint with access token
    Wristband-->>App: Returns claims about the authenticated user
    App->>Browser: Redirects to homepage or requested deep link

Application-Level vs. Tenant-Level Login

Wristband is designed for multi-tenant applications, where each user belongs to a tenant and each tenant has its own dedicated login page. To authenticate a user, Wristband must first identify their tenant so it can direct them to the appropriate login page.

However, the user's tenant may not always be known when authentication begins. To accommodate both scenarios, Wristband supports two login flows:

1. Application-Level Login: Used when the user's tenant is not known upfront. Wristband initiates a tenant discovery flow to determine which tenant the user wants to access.
2. Tenant-Level Login: Used when the user's tenant is already known. Wristband directs the user to their tenant's login page, bypassing tenant discovery.

The following sections explain how to initiate each login flow and how they differ in behavior.

Application-Level Login

How to Initiate: Call the Authorize Endpoint using your application's vanity domain.

Behavior: Wristband initiates the tenant discovery flow, prompting the user to identify the tenant they want to access. Once the tenant is identified, Wristband redirects the user to that tenant's login page to complete authentication.

Configuration Requirement: Application-level login requires the application's Authorization Requests Enabled setting to be set to true.

Tenant-Level Login

How to Initiate: You can initiate tenant-level login in one of two ways:

1. Use a Tenant Vanity Domain: Call the Authorize Endpoint using the tenant's vanity domain. Wristband identifies the tenant from the domain and directs the user to its login page.
2. Use a Tenant Hint: Call the Authorize Endpoint using your application's vanity domain and include the tenant_hint query parameter, set to the tenant's unique name within your application. Wristband uses this hint to identify the tenant and direct the user to its login page.

Behavior: Wristband directs the user to the identified tenant's login page, bypassing the tenant discovery flow.

Authentication Sessions

When a user successfully authenticates with Wristband, Wristband creates an authentication session cookie that references a server-side session maintained by Wristband. The cookie is associated with the vanity domain of the user's tenant, allowing users to maintain separate authentication sessions across multiple tenants without the session cookies conflicting with one another.

When a request is sent to the Wristband Authorize Endpoint, Wristband checks for a valid authentication session cookie. If one is present, Wristband automatically authenticates the user without requiring them to re-enter their credentials.

To learn more, see the Authentication Sessions documentation.

Refresh Tokens

Refresh tokens allow your application to obtain new access tokens without requiring the user to reauthenticate. Access tokens typically have short expiration times, while refresh tokens remain valid for much longer, allowing your application to maintain access to protected resources across multiple access token lifetimes.

When your application exchanges an authorization code at Wristband's Token Endpoint, the response includes a refresh token if the offline_access scope was included in the original authorization request.

To obtain a new access token, call the Token Endpoint using the refresh_token grant type and include the refresh token in the request body. If the request succeeds, Wristband returns a new access token that your application can use to continue accessing protected resources.

Logout

When a user logs out of your application, all authentication-related state must be cleared. This includes two resources managed by Wristband:

• Refresh Token: If a refresh token was issued by the Token Endpoint, it must be revoked to prevent it from being used to obtain new access tokens.
• Authentication Session: The user's authentication session must be terminated to prevent the user from being automatically re-authenticated by Wristband.

Revoking the Refresh Token

To revoke the user's refresh token, call the Revoke Token API, passing the refresh token in the token parameter of the request body.

Terminating the Authentication Session

To terminate the user's Wristband authentication session, redirect their browser to the Logout Endpoint using the vanity domain of the tenant they belong to.

A browser redirect is required because the authentication session is maintained through a cookie associated with the tenant's vanity domain. Redirecting the browser to the Logout Endpoint ensures that the session cookie is included in the request, allowing Wristband to identify and terminate the correct authentication session.