Domains and URLs

Default Vanity Domains

All applications and tenants created in Wristband are assigned a default vanity domain. These vanity domains uniquely identify an application or tenant within Wristband and are used to generate URLs for multiple purposes throughout the Wristband platform. In the sections below, we'll dive into how the vanity domains are structured and what they are used for.

Application Vanity Domains

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

• Making API calls to the Wristband platform.
• Locations of any application-level hosted pages in Wristband.
• OAuth 2 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: This is the company domain name that is provided when a new account is created in Wristband.
• Application Domain Name: This is the domainName field that is specified when a new application is created.

Tenant Vanity Domains

Like applications, when you create a tenant in Wristband, a unique vanity domain is assigned to it. 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.
• The domains of Wristband authentication session cookies.
• For OAuth 2 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.

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 at the beginning of the domain:

• Tenant Domain Name: This is the domainName field that is specified when a tenant is created.

Custom Domains

If you want to override the application or tenant default vanity domains, you can do so by creating a custom domain. Using custom domains can provide the following benefits to your application:

• Increased trust since the application’s domain is preserved while navigating to Wristband’s hosted pages.
• Preservation of brand identity.
• Better looking and more memorable URLs.

ℹ️

Our custom domains are powered by SaaS Custom Domains

Application Custom Domains

Using application custom domains, you can override the default application vanity domain and set it to a domain of your choice. When an application custom domain is created, all tenants under the application will also use the application custom domain; however, to ensure that the tenant's vanity domain is unique, the tenant's domainName attribute will be used as a subdomain of the application's custom domain. For example, if you created an application custom domain with a value of auth.yourapp.io, all tenants under the application would get their own unique vanity domain, with the format <tenan_domain_name>.auth.yourapp.io. So, if you had a tenant whose domain name was customer01 then their domain name would be: customer01.auth.yourapp.io.

Tenant Custom Domains

Tenants in a Wristband can also have their own fully customized domain. Tenant custom domains allow tenants to completely white-label their login experience. Note that if both an application custom domain and a tenant custom domain are defined, the tenant custom domain will take precedence. Therefore, you can have a mix of tenants with vanity domains derived from an application custom domain and tenants with fully customized domains.

The Affects of Enabling Custom Domains

Enabling custom domains affects various aspects of the Wristband platform. In the following sections, we will highlight the main changes that occur when custom domains are enabled.

Hosted Pages

Without custom domains, Wristband's hosted pages will use the default application and tenant vanity domains for the URL locations. However, when custom domains are defined, the location of these hosted pages will instead utilize the custom domains.

Email Action Links

Without custom domains, the action link URLs in emails sent by Wristband will use default vanity domains. However, after enabling custom domains, all email action links will use custom domain values instead.

API URLs

Without custom domains, API calls made to the Wristband platform, use the default application vanity domain. However, when application custom domains are enabled, the application custom domain should be used instead. Note, even with application custom domains enabled, the default application vanity domain can still be used to call Wristband APIs. This ensures that existing Wristband API calls don't break when enabling custom domains.

Token Claims

Without custom domains, the issuer claim within access tokens and ID tokens will use the default application vanity domain. However, when application custom domains are enabled, the value of the issuer claim will use the application custom domain instead.

Authentication Session Cookies

When a user logs in, Wristband creates an authentication session cookie to persist the user's authenticated state. The domain that the authentication session cookie is associated with depends on the domain used to call the Wristband Authorize API. For example, if the default tenant vanity domain was used to call the Authorize API, the auth session cookie will be associated with the default tenant vanity domain. On the other hand, if a tenant custom domain was used to call the Authorize API, then the auth session cookie will be associated with the tenant custom domain.

In addition to the login flow, the following workflows can also trigger the creation of an authentication session cookie:

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

For these workflows, the authentication session cookie is always associated with the active tenant vanity domain. For example, if no custom domains are enabled, the session cookie will be associated with the default tenant vanity domain. However, if custom domains are enabled, then the session cookie will be associated with the tenant's custom domain.

External Identity Provider URLs

When configuring external identity providers, redirect URLs will be generated so that the external identity provider can redirect back to Wristband after authenticating the user. If no custom domains are enabled, the redirect URLs will use the default vanity domains. However, if custom domains are enabled, the redirect URLs will be generated using the custom domains. Note that if an external identity provider was previously configured using a default vanity domain redirect URL, even after enabling custom domains, the default vanity domains will continue to work. This means that you don't have to worry about previous identity provider integrations breaking if custom domains are enabled.

Injecting Tenant Domains Into Your Applicaton's URLs

There are certain scenarios where Wristband needs to redirect back to your application. For example, after a user successfully logs in, Wristband will redirect to your application's Callback Endpoint. When performing these redirects to your application, Wristband can dynamically inject the tenant's domain name into the URL. This is primarily useful if your application uses tenant subdomains and you would like to preserve these tenant subdomains for the endpoints that Wristband redirects to.

To have Wristband dynamically insert the tenant domain name into URLs, you need to use the {tenant_domain} token when configuring the URL in Wristband. The {tenant_domain} token must always be the leftmost domain label in the URL's host, and only one token can be present in the URL.

To illustrate how the {tenant_domain} token can be used; let's look at an example where a user has configured their OAuth 2 client redirect URL to be:

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

Now imagine a situation where a user successfully logs into a tenant whose domain name is customer01. In this case, when Wristband redirects back to the OAuth 2 client's redirect URL, it will replace the {tenant_domain} token in the URL with the tenant's actual domain name so that the final URL that gets redirected to looks like the following:

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

Below is a table showing all the places where the {tenant_domain} token is allowed.