Platform

Custom domains

Use custom domains to provide a seamless, fully branded authentication experience for your users.

Add a custom domain

  1. Navigate to Tenant settings → Custom domains in the Admin UI.
  2. Add your domain and copy the verification DNS records.
  3. Configure your DNS provider, then verify the domain in Authalla.

HTTPS and certificates

Authalla provisions and renews TLS certificates automatically once DNS is verified.

Redirect URLs

Make sure your redirect URLs and allowed origins are updated to use the new domain.

title: Tenant Custom Domains nextjs: metadata: title: Tenant Custom Domains description: Learn how to attach a custom domain to your tenant and serve OAuth2 flows from your own domain.

Attaching a custom domain to your tenant allows you to serve login pages and OAuth2 endpoints from your own domain (e.g., auth.yourcompany.com) instead of the default {tenant-id}.authalla.com subdomain. This provides a more branded experience and can help with security policies that require authentication to happen on your own domain.

Overview

When you attach a custom domain to a tenant:

  • All OAuth2/OIDC endpoints become available on your custom domain
  • Token issuer (iss claim) changes to your custom domain
  • OpenID Connect discovery automatically reflects the new domain
  • SSO callback URLs update to use your custom domain
  • Sessions are domain-scoped - users logged in on your custom domain have separate sessions from the default domain

The system uses DNS-based verification to ensure you own the domain, and Cloudflare handles SSL certificate provisioning automatically.

Prerequisites

Before attaching a custom domain, ensure you have:

  • Access to your domain's DNS settings - You'll need to add DNS records
  • A subdomain (e.g., auth.example.com) - Apex/root domains typically cannot use CNAME records, which are required for routing
  • Domain availability - The domain must be globally unique across all Authalla tenants

Important constraints:

  • Only one custom domain per tenant is currently supported
  • The domain must be available (not already in use by another tenant)

Step-by-Step Setup

1. Add Your Custom Domain

Navigate to your tenant in the Admin UI and go to the Domain tab, or use the Admin API:

Admin UI:

  1. Go to Tenants → Select your tenant → Domain tab
  2. Click Add Domain
  3. Enter your domain (e.g., auth.yourcompany.com)
  4. Click Add Domain

Admin API:

POST /custom-domains
{
  "domain": "auth.yourcompany.com",
  "tenant_id": "your-tenant-id"
}

2. Configure DNS Records

After adding the domain, you'll see the required DNS records in the Admin UI. Add these exactly as shown to your domain provider:

Required DNS Records:

  1. CNAME Record (required)

    • Name: Your custom domain (e.g., auth.yourcompany.com)
    • Value: {tenant-public-id}.authalla.com
    • Purpose: Routes traffic through Authalla's infrastructure

  2. TXT Record (if provided)

    • Name: _cf-custom-hostname.{your-domain} (provided by Cloudflare)
    • Value: The verification value (provided by Cloudflare)
    • Purpose: Verifies domain ownership for Cloudflare

Example DNS Configuration:

Type    Name                    Value
CNAME   auth.yourcompany.com    abc123.authalla.com
TXT     _cf-custom-hostname...  cf-verification-value

3. Wait for Verification

After adding the DNS records:

  1. Status will show as "Pending" - Cloudflare is verifying DNS records and provisioning SSL certificates
  2. Verification typically takes 5-15 minutes - DNS propagation and SSL certificate issuance can take time
  3. Status changes to "Active" - Once verified, your custom domain is ready to use

You can click Retry in the Admin UI to trigger a re-verification check if needed.

After Activation

Once your domain status is Active, the following changes take effect:

OAuth2/OIDC Endpoints

All OAuth2 and OpenID Connect endpoints are now available on your custom domain:

  • https://{your-domain}/.well-known/openid-configuration - OpenID Connect discovery
  • https://{your-domain}/.well-known/jwks.json - JSON Web Key Set
  • https://{your-domain}/oauth2/authorize - Authorization endpoint
  • https://{your-domain}/oauth2/token - Token endpoint
  • https://{your-domain}/oauth2/userinfo - UserInfo endpoint
  • https://{your-domain}/oauth2/logout - Logout endpoint

Token Issuer Changes

Important: The iss (issuer) claim in tokens changes based on which domain you use to access the token endpoint:

  • Using custom domain: iss = https://{your-domain}
  • Using default domain: iss = https://{tenant-id}.authalla.com

Your OAuth2 clients must use the matching issuer/discovery URL. If you switch to a custom domain, update your client configuration to use:

https://{your-domain}/.well-known/openid-configuration

SSO Callback URLs

If you use social login or enterprise SSO, the callback URLs automatically update to use your custom domain:

Social Login Callback:

https://{your-domain}/oauth2/social-login-callback

Enterprise OIDC SSO Callback:

https://{your-domain}/oauth2/enterprise-sso-callback

Enterprise SAML ACS URL:

https://{your-domain}/saml/acs

Action Required: Update your SSO provider configurations (Google, Microsoft, Okta, etc.) with the new callback URLs. The Admin UI will show the updated redirect URI in the SSO connection details.

Session Behavior

Sessions are host-scoped by browsers. This means:

  • Users logged in on https://{your-domain} have a separate session from https://{tenant-id}.authalla.com
  • Cookies are not shared between the two domains
  • Users must log in separately on each domain

Troubleshooting

Domain Status Stuck on "Pending"

Possible causes:

  1. DNS records not yet propagated - DNS changes can take up to 48 hours, though typically propagate within minutes
  2. Incorrect DNS record values - Double-check that the CNAME value exactly matches {tenant-public-id}.authalla.com
  3. TXT record missing - If a TXT record is shown, ensure it's added exactly as provided

Solutions:

  • Verify DNS records using dig or online DNS lookup tools
  • Click Retry in the Admin UI to trigger re-verification
  • Ensure DNS records are added at the correct DNS provider (check for multiple DNS providers)

Domain Status Shows "Error"

Common causes:

  1. CNAME record missing or incorrect - The domain must have a CNAME pointing to {tenant-public-id}.authalla.com
  2. DNS propagation issues - Records may not have propagated yet
  3. Cloudflare verification failure - Check for verification errors in the domain details

Solutions:

  • Verify the CNAME record exists and points to the correct value
  • Wait a few minutes and click Retry
  • Check the error message in the Admin UI for specific verification errors

OAuth2 Clients Not Working After Activation

If clients stop working after activating a custom domain:

  1. Update issuer/discovery URL - Clients must use the new discovery endpoint:

    https://{your-domain}/.well-known/openid-configuration

  2. Verify token issuer - Check that tokens have iss = https://{your-domain}

  3. Update redirect URIs - Ensure client redirect URIs match the new domain if you're using domain-specific redirects

Removing a Custom Domain

To remove a custom domain:

  1. Go to Tenants → Select your tenant → Domain tab
  2. Click the Remove button
  3. Confirm removal

What happens when you remove a domain:

  • OAuth2 flows revert to using https://{tenant-id}.authalla.com
  • Token issuer reverts to the default domain
  • SSO callback URLs revert to the default domain
  • Action required: Update your SSO provider configurations back to the default callback URLs
  • Users with active sessions on the custom domain will need to log in again on the default domain

The default domain ({tenant-id}.authalla.com) continues to work throughout this process - removing a custom domain doesn't affect existing functionality.

Technical Details

How It Works

  1. Tenant Resolution: The system extracts the tenant from the Host header in incoming requests.

  2. DNS Routing: The CNAME record routes traffic to Authalla's infrastructure, which then routes to the correct tenant based on the custom domain.

  3. SSL Certificates: Cloudflare automatically provisions and manages SSL certificates for your custom domain using Domain Validation (DV) certificates.

  4. Endpoint Generation: All OAuth2/OIDC endpoints are dynamically generated based on the request host, so they automatically work on your custom domain.

Domain Verification Flow

  1. You add the domain in Admin UI/API
  2. Cloudflare creates a custom hostname and provides verification records
  3. You add the DNS records (CNAME + optional TXT)
  4. Cloudflare verifies DNS records and provisions SSL certificate
  5. Status changes to "Active" when verification completes
Previous
Tenant setup
Next
Branding & theming