Login Workflow
Authenticate users into your application through Wristband's login flow.
Wristband handles login for users authenticating into your application, supporting multiple identity providers and login methods within a single, unified flow.
When a user initiates login, your application's Login Endpoint creates an authorization request and redirects to Wristband. From there, Wristband routes the user to the appropriate login experience based on your configuration: either Wristband-hosted pages or your own self-hosted UI. After successful authentication, Wristband issues an authorization code that your Callback Endpoint exchanges for tokens to establish an application session.
Workflow Policies
The Login Workflow Policies control behavior for specific login scenarios. They can be set at the application level and optionally overridden per tenant.
The Login workflow policy includes the following settings:
- Allow Changing Tenant: When enabled, users on the Tenant-level Login Page are shown a link at the bottom of the form to return to Application-level login and select a different tenant.
- Missing Password Remediation Strategy: When enabled, users who have no password set are prompted to complete a password reset before they can proceed. This only applies when logging in with the Wristband Identity Provider.
Login Workflow Policies in the Wristband Dashboard
Additionally, the Enterprise IdP Login (SSO) workflow policy includes the following setting:
- Email Verification Strategy: Controls whether Wristband uses the Email Verification Workflow or a one-time code to verify the user's email during enterprise SSO login.
Note: When the email verification workflow strategy is selected, it is triggered when the user is first provisioned or if their email is updated during profile sync.
Enterprise IdP Login (SSO) Workflow Policies in the Wristband Dashboard
Application-Level vs Tenant-Level Login
In Wristband, users can interact with two phases of the login process.
Application-Level Login
Users can access the Application-level Login page for Tenant Discovery. This page directs the user to the specific Tenant-level login page they wish to access, akin to using a directory in a mall to find a specific store.
Learn more on the Tenant Discovery documentation page.
Tenant-Level Login
The Tenant-level Login Page is the second and final login page a user interacts with during authentication. Users typically perform tenant discovery on the Application-level Login page to reach the Tenant-level Login Page. It is also possible to bookmark the URL of the Tenant-level Login Page to bypass Application-level Login. When accessing this page, your application's Login Endpoint must redirect to the Wristband Authorize Endpoint to start an authorization request. This page can be accessed directly and bookmarked if the URL is known in advance.
Tenant-level Login Page showing user credential fields
Login URLs for Wristband-hosted Pages
There are publicly available URLs where you can reach the Wristband-hosted Login Pages for both the Application level and the Tenant level (if multi-tenant).
Wristband Vanity Domains
Let's say we have a Wristband application named yourapp with a tenant named yourcustomer, the URLs would be as follows:
| Login Type | URL |
|---|---|
| Application Level | https://yourapp-yourcompany.us.wristband.dev/login |
| Tenant Level | https://yourcustomer-yourapp-yourcompany.us.wristband.dev/login |
Custom Domains
For a custom domain auth.yourapp.io, the URLs would be:
| Login Type | URL |
|---|---|
| Application Level | https://auth.yourapp.io/login |
| Tenant Level | https://yourcustomer.auth.yourapp.io/login |
Supported Query Parameters
The URLs for the Wristband-hosted Login pages can support certain query parameters:
| Query Parameter | Required | Supported Login Pages | Description |
|---|---|---|---|
req | Yes | Tenant-level Login | The authorization request JWT used by the Login Page to infer your application's original authorization request parameters. The request parameters must have initially been passed as query parameters when redirecting from your application's Login Endpoint to the Wristband Authorize Endpoint. |
client_id | No | Application-level Login | Specifies the clientId associated with the desired OAuth2 Client whose login URL you intend to utilize. Include this query parameter when navigating to the Application-level Login Page to ensure continuity. |
Multi-Factor Authentication
MFA can be layered on top of any Wristband Identity Provider login method. When MFA is required and the user has enrolled an authenticator, Wristband challenges the user with a second factor after primary credential verification succeeds. The MFA Workflow is triggered as part of the login flow. See MFA Workflow for details.
Updated 6 days ago