Custom Domains

Custom domains allow you to serve Auris hosted login pages, OIDC Discovery endpoints, and email links under your own domain. Instead of your users seeing the Auris platform URL during authentication, they see your branded domain — for example, auth.yourcompany.com.

Access custom domain management at Console → Settings → Custom Domains.

Why Custom Domains Matter

When a user clicks “Sign In” in your application, they are redirected to the Auris hosted login page. Without a custom domain, the browser’s address bar shows the Auris platform URL. With a custom domain:

• Trust: Users see your domain during authentication, building trust
• Branding: The entire login experience appears to be operated by your organization
• Email links: Password reset links, magic links, and verification emails come from your domain
• OIDC Discovery: The /.well-known/openid-configuration document references your domain, which matters for integrations that inspect issuer URLs

Custom Domains Page Overview

The Custom Domains page displays all registered domains for your tenant:

Adding a Domain

DNS Verification Flow

After adding a domain, you need to prove ownership by configuring DNS records at your DNS provider.

Viewing Required DNS Records

Click the domain in the list to open the detail view. The Verification section shows the DNS records you need to create.

Auris generates a unique verification token for your domain. You can verify using one of two methods:

CNAME Verification (Recommended)

Create a CNAME record that points your subdomain to the Auris platform hostname:

Type:   CNAME
Name:   auth         (just the subdomain part, without your root domain)
Value:  proxy.auris.example.com    (shown in the Console)
TTL:    300          (5 minutes, or your provider's minimum)

CNAME is the recommended method because:

• It handles both verification and routing in a single record
• Traffic for your custom domain is automatically routed to Auris
• No additional configuration is needed after verification

TXT Verification

If you cannot create a CNAME record (for example, if a CNAME already exists for the subdomain), use TXT verification:

Type:   TXT
Name:   _auris-verification.auth    (shown in the Console)
Value:  auris-verify=abc123def456    (unique token shown in the Console)
TTL:    300

With TXT verification, you still need to set up routing separately (for example, via an A record or a CNAME at a different subdomain).

Copying the Verification Token

The Console provides a Copy button next to each DNS value. Click it to copy the exact string to your clipboard, avoiding typos.

DNS Propagation

After creating the DNS records at your provider, propagation typically takes:

You can verify propagation yourself using a DNS lookup tool:

dig CNAME auth.yourcompany.com
# or
nslookup -type=CNAME auth.yourcompany.com

Clicking Verify

Once you believe DNS has propagated:

1. Return to the Custom Domains page in the Console
2. Click Verify next to your domain
3. Auris performs a DNS lookup to check for the expected records

If verification succeeds, the status changes to Active. If it fails, the status changes to Failed with an error message indicating what was expected versus what was found.

Status Indicators

Domain Verification Status

SSL Certificate Status

Once a domain is verified, Auris automatically provisions an SSL/TLS certificate:

Setting a Primary Domain

After a domain reaches Active status (verified with active SSL), you can set it as the primary domain:

1. Click the domain in the list
2. Click Set as Primary
3. Confirm the change

The primary domain is used for:

Only one domain can be primary at a time. Setting a new primary domain automatically removes the primary flag from the previous one.

Switching Primary Domains

You can switch the primary domain at any time. The change takes effect immediately for new authentication flows. Existing tokens retain their original iss claim until they expire.

When switching from domain A to domain B:

• New logins use domain B
• In-flight authentication flows (already redirected to domain A) complete normally on domain A
• Existing access tokens with iss: "https://domain-a.example.com" remain valid until expiry
• New access tokens use iss: "https://domain-b.example.com"

Deleting a Domain

To remove a custom domain:

1. Click the domain in the list to open the detail view
2. Click Delete
3. Confirm the deletion

If the domain being deleted is the primary domain, authentication falls back to the Auris platform URL.

Important considerations before deleting:

• Applications configured with redirect_uri containing the custom domain will break if the domain is deleted
• OIDC clients that validate the iss claim against the custom domain will reject new tokens
• Email links in recently sent emails (password reset, magic link) will stop working

Update your application configuration before deleting a domain to avoid disruption.

Multiple Domains

You can register multiple custom domains for a single tenant. Common use cases:

All domains share the same tenant configuration (users, roles, security settings). The primary domain determines which domain appears in emails and OIDC metadata.

Non-primary domains are still functional for authentication — you can direct specific applications to use a non-primary domain by setting the appropriate redirect URIs in the application configuration. However, email links and OIDC Discovery will always reference the primary domain.

Related Guides

• Branding & Customization — Logo, colors, and email template customization
• Multi-Tenancy — How custom domains fit into the tenant model
• Hosted Login Flow — How the OAuth2 flow uses custom domains
• Applications — Configure redirect URIs for your custom domain