Domains and URLs

This section will show you what URLs in Wristband look like and how both application vanity domains as well as tenant vanity domains come into play. We'll also look at the consequences of using custom domains.

Vanity Domains

Application-Level

When you create an application in Wristband, a vanity domain is assigned to it in order to uniquely identify it in our platform. Application vanity domains are used for the following:

• Making API calls to the Wristband platform
• Locations of any application-level hosted pages in Wristband
• OAuth2 redirect URIs for identity providers defined at the application level
• For the issuer claim inside access and ID tokens

Here is a breakdown of the structure of default application-level vanity domains in Wristband:

Working from right to left on each of the domain parts:

• Wristband's Apex Domain: This is the root domain.
• Region: The geographic region in the Wristband cloud where the application is deployed.
• Tenant Account Name: When you sign up with Wristband, you are asked to choose a Company subdomain for the Wristband dashboard. This represents your own organization's tenant within the Wristband platform for all of your applications.
• Application Domain Name: When you create new applications, this is the domainName field that is required upon creation.

Tenant-Level

For tenants under an application, a unique vanity domain is assigned to each tenant in order to uniquely identify them in our platform. Tenant vanity domains are used for the following:

• Locations of any tenant-level hosted pages in Wristband
• Endpoints that you redirect to as part of authentication workflows, including the authorize and logout endpoints.
• For OAuth2 redirect URIs for identity providers defined at the tenant level
• For the SAML ACS URLs and SP entity IDs for identity providers defined at the tenant level

Note About Authenticated Sessions

The authentication session cookie will be associated with the tenant vanity domain.

Here is a breakdown of the structure of default tenant-level vanity domains in Wristband:

The structure is the same as default application-level domains, except there is one additional part in the beginning of the domain:

• Tenant Domain Name: When you create new tenants under an application, this is the domainName field that is required upon creation.

App-level Custom Domains (Tenant Subdomains)

Instead of relying on the predefined vanity domains that Wristband provides by default, you can override the vanity domains to use a custom domain of your choice. Custom domains are configured for an application and apply for all tenants under that application.

For example, let's say your vanity domain in Wristband is yourapp-wristband.us.wristband.dev. Now you enable custom domains for your application with a value of auth.yourapp.io. All tenants under the application would get their own unique vanity domain, such as customer01.auth.yourapp.io.

Developers of B2B applications want per-tenant custom domains to achieve the following:

• Better security and privacy compliance regarding Intelligent Tracking Protection (ITP) and third-party cookies

Customers of B2B applications want per-tenant custom domains to achieve the following:

• Increased trust when using the application since the application’s domain is preserved while navigating Wristband’s hosted pages.
• Greater sense of ownership and control over their login pages
• Preservation of their brand identity
• Visual appeal and enhanced memorability of URLs

Enabling custom domains has a broad affect across a handful of areas in the Wristband platform.

Hosted Pages

Any page that Wristband hosts will use the default application and tenant vanity domains for the URL locations. When custom domains for an application are applied, the location of these hosted pages will instead rely on the custom domains.

Email Action Links

For all transactional emails that Wristband sends to users on behalf of your application, the action link URLs in the email content use default vanity domains out of the box. Enabling custom domains for your application will make all email action links use that new custom domain value instead.

API URLs

For any API calls made to the Wristband platform, you would use the application vanity domain out of the box. When custom domains are enabled, you would use the value of your desired custom domain instead.

Access and ID Tokens

All access tokens and ID tokens that are generated by Wristband contain an Issuer claim, which is a string that identifies the principal that issued the JWT. When you enable a custom domain, the value for this claim will show that custom domain instead of the default vanity domain.

Authentication Session Cookies

When the user calls the Authorize API, the domain used to call that endpoint will be the domain that the auth session cookie is associated to. So if the default vanity domain was used to call the Authorize API, then the auth session cookie will be associated with the default vanity domain. On the other hand, if a custom domain was used to call the Authorize API, then the auth session cookie will be associated to the custom domain.

There are a couple other flows that can trigger the creation of a session such as:

• Signup
• New User Invite
• Existing User Invite
• Forgot Password (if the "Immediate Login" workflow policy is enabled).

For these flows, the auth session cookie will be associated with the default vanity domain. If there is an active custom domain, then it will get associated with the active custom domain.

External Identity Providers

When configuring external identity providers for Wristband (both Social and Enterprise), you are provided:

• A redirect URL for OIDC-based IDPs
• An ACS URL and SP Entity ID for SAML-based IDPs

Enabling custom domains for your application will replace the default vanity domains with your custom domain values.

📘

Different Vanity Domains per Protocol

Application-level OIDC-based IDPs use the application vanity domain. Tenant-level IDPs (both OIDC and SAML) use the tenant vanity domain.

Tenant Domain Token for Your Applicaton's URLs

Your customer can reach certain Wristband-hosted auth pages by using a tenant vanity domain in the URL, such as on the Tenant-level login page. To achieve that, Wristband would invoke your application's auth endpoints (Login, Callback, etc.) with a tenant vanity domain (or custom domain). In order to tell Wristband to generate these dynamic tenant vanity domains on a per-tenant basis, you need to configure specific URLs in your Wristband application to include the Tenant Domain Token. This token is represented by the string value {tenant_domain} (note that the included bracket characters are part of the value).

As an example, you might configure the value of loginUrl on the Application entity as follows:

https://{tenant_domain}.yourapp.io/auth/login

Imagine a situation where an end user, who belongs to the Customer01 tenant, logs out of your application. In this case, your application's Logout endpoint triggers a redirection to Wristband using a tenant vanity domain that looks like the following:

https://customer01-dashboard-wristband.us.wristband.dev/api/v1/logout?client_id=123

Following the termination of the user's authenticated session, Wristband substitutes the configured {tenant_domain} value in your loginUrl (configured in Wristband) with the specific domain name of the tenant to which the end user belongs. Subsequently, Wristband utilizes the resolved value of your loginUrl and redirects to your application's Login endpoint, incorporating the tenant domain label in the URL. It would look like the following:

https://customer01.yourapp.io/auth/login

Tenant Domain Structure

Note that the Tenant Domain Token is always the left-most domain label in the URL's host, and it is always the first text present immediately to the right of the protocol. The Tenant Domain Token cannot reside anywhere else in the URL, and there can only be one Tenant Domain Token present in the URL.

It is not a strict requirement to leverage Tenant Domain Tokens. However, using them preserves the tenant vanity domain experience (and custom domains, too) on Wristband-hosted auth pages. There are a few different URLs in Wristband that can be configured to include the Tenant Domain Token to effectively utilize tenant vanity domains:

If you opt not to utilize the Tenant Domain Token in the URLs configured in Wristband, you still need a way for Wristband to pass tenant domain information to your multi-tenant application during the Authorization Code Flow. This can be achieved by exposing a tenant_domain query parameter in your application's Login endpoint which redirects to the Wristband Authorize Endpoint. For instance, considering the example above where the Wristband Logout Endpoint redirects back to your application's Login endpoint, Wristband would pass the tenant domain as follows:

https://yourapp.io/auth/login?tenant_domain=customer01

Tenant Custom Domains

Tenants in a Wristband application can also have a fully custom tenant domain (e.g. tenant.com) as opposed to just a subdomain under a shared app domain (e.g. tenant.yourapp.io). All the principles outlined in the above sections also apply to tenant custom domains, except for the {tenant_domain} token, as tenant custom domains take precedence over custom application domains with tenant subdomains. All tenant types can have a fully custom tenant domain.

Providing each tenant with a full custom domain amplifies all the benefits of application-level custom domains with tenant subdomains, enhancing the tenant's brand identity to the highest degree. Tenant custom domains are particularly useful in several scenarios, including:

• Fully white-label applications, especially when your customers are resellers of your software
• Standard multi-tenant applications that need to meet enterprise requirements for complete product white labeling
• Global tenants seeking to present a consumer-specific URL