Implementing Authentication Endpoints

Learn how to implement the core Wristband authentication endpoints within your application.

Overview

To integrate Wristband's user authentication flow into your application, you'll need to implement three endpoints on your backend server:

  • Login Endpoint: Initiates authentication by redirecting the user's browser to Wristband's Authorize Endpoint.
  • Callback Endpoint: Processes the authentication response from Wristband, exchanges the authorization code for tokens, and establishes an application session.
  • Logout Endpoint: Clears the application session and redirects the browser to Wristband's Logout Endpoint to complete the logout process.

Wristband Auth SDKs

Wristband's Auth SDKs provide built-in support for implementing these authentication endpoints, eliminating the need to manually handle much of the integration logic.

See the Authentication SDKs documentation for available SDKs and their integration requirements.

Login Endpoint

The Login Endpoint initiates the authentication flow by constructing an OIDC authorization request and redirecting the user's browser to Wristband's Authorize Endpoint.

How the Login Endpoint Works

The Login Endpoint performs the following steps:

  1. Preserve Login State: Generate and securely store any state needed to complete the authentication flow, including the OAuth2 state value, PKCE code verifier, redirect URI, and optional return URL.
  2. Construct the Authorization Request: Build the authorization request URL with the required parameters, including the client ID, redirect URI, requested scopes, state, and PKCE code challenge.
  3. Redirect to Wristband: Return an HTTP 302 redirect to Wristband's Authorize Endpoint to initiate authentication.

Application-Level vs. Tenant-Level Login

Your Login Endpoint must determine whether to initiate an application-level or tenant-level login based on whether the user's tenant is known.

  • Application-Level Login: When the user's tenant is unknown, your Login Endpoint can redirect the browser to Wristband's Authorize Endpoint using the application's vanity domain. Wristband initiates tenant discovery to identify the user's tenant before directing them to the appropriate login page. This requires application-level authorization requests to be enabled.

  • Tenant-Level Login: When the user's tenant is known, your Login Endpoint can redirect the browser to Wristband's Authorize Endpoint using the tenant's vanity domain. Alternatively, it can use the application's vanity domain with the tenant_hint query parameter set to the tenant's unique name. Wristband directs the user to the tenant's login page without requiring tenant discovery.

Your Login Endpoint can use tenant information from the incoming request, such as the tenant_name or tenant_custom_domain query parameters, to determine the appropriate authorization URL.

Preserving Login State

Before redirecting the user to Wristband, your Login Endpoint must preserve certain information needed by the Callback Endpoint to complete the authentication flow.

Common state values include:

  • OAuth2 State: A cryptographically random string used to identify the login attempt and protect against login CSRF attacks.
  • PKCE Code Verifier: A cryptographically random string used during the authorization code exchange.
  • Redirect URI: The callback URL used in the original authorization request and subsequent token exchange.
  • Return URL: An optional application URL where the user should be redirected after successful authentication.

One approach is to store this information in a temporary, encrypted Login State Cookie. This allows your application to securely transfer state between the Login and Callback Endpoints without requiring an external session datastore.

How the Login State Cookie Works

The following steps describe how to preserve login state using a browser cookie:

  1. Generate Login State: When the Login Endpoint receives a request, generate a cryptographically random OAuth2 state value and a separate PKCE code verifier. Combine the code verifier, redirect URI, and any optional information, such as a return URL, into a login state object.

  2. Create the Login State Cookie: Encrypt the login state object and store it in a browser cookie. Use the generated state value as part of the cookie's name, allowing the Callback Endpoint to identify the correct cookie later. Configure the cookie with HttpOnly, Secure, and SameSite=Lax, along with a short expiration time. Ensure the cookie's domain is configured so the browser includes it in requests to the Callback Endpoint.

  3. Redirect to Wristband: Construct the authorization request using the generated state value as the OAuth2 state query parameter. Redirect the user's browser to Wristband's Authorize Endpoint.

  4. Retrieve the Login State Cookie: After authentication, Wristband redirects the browser to your application's Callback Endpoint, returning the original state value as a query parameter. The browser automatically includes the Login State Cookie with this request. The Callback Endpoint uses the returned state value to locate the corresponding cookie.

  5. Complete Authentication: The Callback Endpoint decrypts and validates the retrieved login state, then uses the stored PKCE code verifier and redirect URI to exchange the authorization code for tokens. Once authentication succeeds, the backend server establishes the application session and clears the temporary Login State Cookie. Finally, the user is redirected to the return URL stored in the login state, if provided, or to the application's default landing page.

Using the OAuth2 state value to identify the Login State Cookie also allows your application to support multiple concurrent login attempts, such as when a user initiates authentication from different browser tabs. Each login attempt has its own uniquely named Login State Cookie, ensuring the Callback Endpoint retrieves the correct state information.

Limiting Concurrent Login State Cookies

Because each login attempt creates a new Login State Cookie, repeatedly calling the Login Endpoint without completing authentication can cause cookies to accumulate in the browser. Over time, this can lead to browser cookie limits being exceeded or HTTP requests being rejected due to oversized Cookie headers.

To prevent this, your application should limit the number of concurrent Login State Cookies maintained by the browser.

For example, Wristband's Auth SDKs use the following approach to limit concurrent login attempts to three:

  1. Identify Existing Cookies: Before creating a new Login State Cookie, inspect the incoming request for existing Login State Cookies.
  2. Enforce the Cookie Limit: If three or more Login State Cookies already exist, identify and clear the oldest cookies, retaining only the two most recent.
  3. Create the New Cookie: Generate and store the new Login State Cookie, bringing the total number of active Login State Cookies to a maximum of three.

To identify the oldest cookies, include a creation timestamp in each cookie's name alongside the OAuth2 state value. This allows the Login Endpoint to determine which cookies should be removed without decrypting their contents.

Additionally, configure Login State Cookies with a short expiration time, such as one hour, so that abandoned login attempts are automatically cleaned up by the browser.

Concurrent Login Considerations

Removing an older Login State Cookie invalidates the corresponding login attempt. If the user completes that authentication flow afterward, the Callback Endpoint will no longer be able to retrieve its login state and should require the user to restart authentication.

Login State Cookie Security

When implementing this approach, consider the following security recommendations:

  • Encrypt Cookie Data: Use authenticated encryption to protect the confidentiality and integrity of the login state, particularly the PKCE code verifier.
  • Use a Short Expiration Time: Configure Login State Cookies to expire after a limited period, such as one hour.
  • Limit Concurrent Cookies: Enforce a maximum number of Login State Cookies to prevent excessive cookie accumulation.
  • Configure Cookie Security Attributes: Enable HttpOnly and Secure, and use SameSite=Lax to allow the cookie to accompany the top-level redirect from Wristband to your Callback Endpoint.
  • Configure Cookie Domain: Ensure the Login State Cookie created by the Login Endpoint is accessible to the Callback Endpoint. If both endpoints use the same hostname, a host-only cookie is sufficient. If they use different subdomains, configure the cookie's Domain attribute to a shared parent domain so the browser includes it in requests to both endpoints.
  • Validate Login State: Verify the retrieved login state against the authorization response before exchanging the authorization code.
  • Clear Cookies After Use: Remove the Login State Cookie once it has been retrieved and processed.
  • Validate Return URLs: If the cookie contains a return URL, validate that it points to an allowed application destination before redirecting the user.

If the Login State Cookie is missing, expired, or invalid, the Callback Endpoint should reject the authentication response and require the user to restart the login flow.

Login State Cookies in Wristband Auth SDKs

Wristband's Auth SDKs use this cookie-based approach to securely preserve authentication state between the Login and Callback Endpoints. The SDKs handle login state generation, cookie encryption, state validation, and cookie cleanup automatically.

See the Authentication SDKs documentation for available SDKs and integration instructions.

Login Endpoint Query Parameters

Your application's Login Endpoint should support the following query parameters to customize the authentication flow.

These parameters can be provided directly by your application when initiating login or automatically included by Wristband when redirecting users to your application's Login Endpoint during certain authentication flows.

ParameterDescription
tenant_nameThe unique name of the tenant the user is logging into. Used to identify the tenant and construct the appropriate authorization request.
tenant_custom_domainThe tenant's active custom domain, if configured. Can be used as the host when constructing the Wristband Authorize Endpoint URL.
login_hintThe email address or username of the user attempting to log in. Can be forwarded to Wristband's Authorize Endpoint to pre-populate the login form.
idp_hintThe name of the identity provider (IdP) the user intends to authenticate with. Can be forwarded to Wristband's Authorize Endpoint to direct the user to a specific IdP.
return_urlAn application URL where the user should be redirected after successful authentication. This parameter is provided by your application to support deep linking and should be preserved in the login state for use by the Callback Endpoint.
stateWhen application-level authorization requests are disabled, Wristband preserves the state value originally passed to its application-level login page and returns it to your application's Login Endpoint after tenant discovery.

When Wristband Passes Query Parameters

Wristband may include additional query parameters when redirecting users to your application's configured Login URL, such as after completing tenant discovery, signup, or invitation flows. These parameters preserve tenant information and login hints needed to initiate the appropriate authentication flow.

Tenant Information

When Wristband knows which tenant the user belongs to, it may include the following parameters:

  • tenant_name: Included when the configured Login URL does not use the {tenant_name} placeholder. If the Login URL uses this placeholder, Wristband substitutes the tenant's name directly into the URL's hostname instead.
  • tenant_custom_domain: Included when the tenant has an active custom domain configured.

For example, suppose your application's configured Login URL is:

https://yourapp.com/auth/login

When Wristband redirects a user associated with the tenant org1, it appends the tenant_name parameter:

https://yourapp.com/auth/login?tenant_name=org1

If the tenant also has an active custom domain of auth.org1.com, Wristband includes the tenant_custom_domain parameter:

https://yourapp.com/auth/login?tenant_name=org1&tenant_custom_domain=auth.org1.com

Your Login Endpoint can use these parameters to identify the tenant and construct the appropriate authorization request to Wristband's Authorize Endpoint.

Login Hints

Wristband may also include the following parameters to preserve information about how the user intends to authenticate:

  • login_hint: Identifies the user's email address or username.
  • idp_hint: Identifies the identity provider the user intends to authenticate with.

When your Login Endpoint receives either parameter, it should forward the value to Wristband's Authorize Endpoint using the corresponding login_hint or idp_hint query parameter.

This allows Wristband to preserve the user's login context across authentication flows.

Deprecated Parameters

The following parameters are passed to the Login Endpoint but are considered deprecated and should no longer be used as they may be removed in future releases:

  • tenant_domain_name: Contains the name of the tenant. The tenant_name parameter should be used instead.

Preserving State During Tenant Discovery

When application-level authorization requests are disabled, users must select a tenant before proceeding with authentication.

If the initial request to Wristband's application-level login page includes a state query parameter, Wristband preserves its value. After the user selects a tenant, Wristband redirects to your application's Login Endpoint and includes the original state value as a query parameter.

This allows your application to preserve the original login context across tenant discovery.

When application-level authorization requests are enabled (the default), Wristband continues the authentication flow directly after tenant discovery without redirecting back to your application's Login Endpoint. Therefore, the state query parameter is not used in this case.

Callback Endpoint

The Callback Endpoint processes the authentication response from Wristband after the user completes the login flow.

Upon successful authentication, Wristband redirects the user's browser to your application's Callback Endpoint with an authorization code. Your backend server exchanges this code for tokens and establishes an authenticated application session.

How the Callback Endpoint Works

The Callback Endpoint performs the following steps:

  1. Inspect the Authorization Response: Check whether Wristband returned an authorization code or an error, and retrieve the OAuth2 state parameter from the callback request.
  2. Retrieve and Validate Login State: Use the returned state value to locate the corresponding Login State Cookie. Decrypt and validate the stored login state, then retrieve the PKCE code verifier, redirect URI, and optional return URL. If the Login State Cookie does not exist or is invalid, the user should be redirected back to the application's Login Endpoint to restart the login process.
  3. Exchange the Authorization Code: Call Wristband's Token Endpoint using the authorization_code grant type to exchange the authorization code for tokens.
  4. Retrieve User Information: Optionally call Wristband's UserInfo Endpoint using the access token to retrieve additional information about the authenticated user.
  5. Establish the Application Session: Create an authenticated application session using the token response and any user information required by your application.
  6. Redirect to the Application: Redirect the user's browser to the application's default landing page or the return URL preserved during the original login request.

Secure Redirect Handling

When using a return_url parameter to support deep linking, validate the destination before redirecting the user. Only allow trusted application URLs to prevent open redirect vulnerabilities.

Similarly, validate tenant-specific domain parameters before using them to construct authentication URLs.

Once the application session is established, subsequent requests can use the session cookie to maintain the user's authenticated state without requiring them to log in again.

For more information about creating, storing, and managing application sessions, see the Session Management documentation.

Callback Endpoint Query Parameters

Your Callback Endpoint should handle the following query parameters returned by Wristband:

ParameterDescription
codeThe authorization code issued after successful authentication. Used to retrieve tokens from Wristband's Token Endpoint.
errorAn error code indicating that the authorization request failed.
error_descriptionAdditional information describing the authorization error.
stateThe state value originally included in the authorization request. Used to validate the callback and retrieve previously stored login state.
tenant_custom_domainThe custom domain of the tenant the user is logged into. Wristband will include this parameter when redirecting to your Callback Endpoint for a tenant with an active custom domain. When provided, it can be forwarded to the Login Endpoint, so that the tenant's custom domain can be used to construct the authorize URL.
tenant_nameThe unique name of the tenant the user logged into. Wristband will include this parameter when redirecting to your Callback Endpoint, if the redirect URI used in the authorization request didn't contain a {tenant_name} placeholder. When provided, it can be forwarded to the Login Endpoint, to construct the tenant's authorize URL.

Deprecated Parameters

The following parameters are passed to the Callback Endpoint but are considered deprecated and should no longer be used as they may be removed in future releases:

  • tenant_domain_name: Contains the name of the tenant. The tenant_name parameter should be used instead.

Handling Authentication Errors

If Wristband returns an error parameter instead of an authorization code, the Callback Endpoint should handle the authentication failure without attempting to exchange a code for tokens.

Depending on the error, your application can display an appropriate error message or redirect the user to the Login Endpoint to restart authentication.

The Callback Endpoint should also clean up any temporary login state associated with the completed or failed authentication attempt.

Logout Endpoint

The Logout Endpoint terminates the user's application session and redirects their browser to Wristband to complete the logout process.

How the Logout Endpoint Works

The Logout Endpoint performs the following steps:

  1. Retrieve Session Information: Retrieve the user's application session, including the refresh token (if available).
  2. Revoke the Refresh Token: If a refresh token is available, call Wristband's Revoke Token API to prevent it from being used to obtain new access tokens.
  3. Clear the Application Session: Clear the application's session cookie and any associated session data.
  4. Redirect to Wristband: Return an HTTP 302 redirect to Wristband's Logout Endpoint to terminate the Wristband authentication session. When redirecting to Wristband's Logout Endpoint, you must use the vanity domain of the tenant the user is logging out of to ensure the correct authentication session is terminated.

After the Wristband authentication session is terminated, Wristband redirects the user's browser to the configured login URL or a specified redirect URL.



Did this page help you?