Multiple Custom Domains Best Practices

Implementing Multiple Custom Domains (MCD) effectively requires thoughtful planning and adherence to best practices. By following these guidelines, you can ensure scalability, maintain robust security, and deliver a consistent brand experience across all your custom domains. This guide covers best practices for planning, security, performance, operations, and user experience when using multiple custom domains.

Verify ownership of domains

Make sure you are ready to verify ownership of your custom domains in a timely manner. Leaving domains unverified for too long can clutter your space and complicate the management process.

Planning and architecture

Choose a domain strategy

Before implementing MCD, decide on your domain strategy:

By brand: Separate custom domains for each brand (e.g., login.brand1.com, login.brand2.com)
By region: Regional domains for compliance or performance (e.g., login.us.example.com, login.eu.example.com)
By customer: Dedicated domains for enterprise customers (e.g., login.customer1.com, login.customer2.com)
Hybrid: Combination of strategies (e.g., brand + region: login-us.brand1.com)

Configure a default domain

Always configure a default custom domain to:

Simplify configuration for applications that don’t need domain-specific behavior
Provide fallback for email notifications
Reduce the need for explicit domain specification in API calls

Best practice: Use a generic or administrative domain as default (e.g., login.company.com or admin.company.com) rather than a brand-specific domain.

Plan for scale

Consider future growth when designing your MCD architecture:

Document domain assignments: Maintain clear documentation of which applications use which domains
Reserve domain patterns: Register domains you may need in the future
Monitor limits: Track your domain count against entitlement limits
Plan for expansion: Design your architecture to accommodate additional domains

Use metadata to stay organized

Leverage the metadata fields available for each custom domain to enable efficient management and customization: Recommended metadata fields:

brand: Brand identifier (e.g., “BrandA”, “BrandB”)
region: Geographic region (e.g., “us-east”, “eu-west”)
environment: Environment type (e.g., “production”, “staging”)
customer_id: Customer or tenant identifier
support_email: Domain-specific support contact
purpose: Domain purpose (e.g., “customer-portal”, “admin-portal”)

Example metadata structure:

{
  "brand": "BrandA",
  "region": "us-east",
  "environment": "production",
  "customer_id": "cust_12345",
  "support_email": "support@brand-a.com",
  "tier": "enterprise"
}

Use metadata for:

Email customization: Personalize email templates based on metadata
Actions logic: Implement domain-specific authentication rules
Filtering and search: Organize domains in your management tooling
Reporting: Track usage and performance by brand, region, or customer

Security

Domain validation in Actions

Use Actions to validate that authentication requests come from expected domains:

exports.onExecutePostLogin = async (event, api) => {
  const domain = event.custom_domain?.domain;

  // List of allowed custom domains
  const allowedDomains = [
    'login.brand1.com',
    'login.brand2.com',
    'login.example.com'
  ];

  if (!domain || !allowedDomains.includes(domain)) {
    return api.access.deny(
      `Authentication from ${domain} is not permitted.`
    );
  }
};

Organization-based access control

Restrict which custom domains can be used to access specific organizations:

exports.onExecutePostLogin = async (event, api) => {
  const domain = event.custom_domain?.domain;

  if (!event.organization) {
    return;
  }

  // Check organization's allowed domains
  const allowedDomains = event.organization.metadata?.allowed_domains?.split(',') || [];

  if (allowedDomains.length > 0 && !allowedDomains.includes(domain)) {
    return api.access.deny(
      `Access to ${event.organization.name} requires authentication via an approved domain.`
    );
  }
};

Certificate management

Monitor expiration: Set up alerts for certificate expiration dates
Automate renewal: Use Auth0-managed certificates for automatic renewal
Document self-managed processes: If using self-managed certificates, maintain clear runbooks

Token validation

Ensure your APIs accept tokens from all configured custom domains:

// Accept multiple issuers
const validIssuers = [
  'https://login.brand1.com/',
  'https://login.brand2.com/',
  'https://login.example.com/'
];

expressjwt({
  // ... other config
  issuer: validIssuers,
  algorithms: ['RS256']
})

Performance

Use regional domains

For global applications, consider using region-specific custom domains to help with data residency requirements and branding by region:

Examples: login-us.example.com, login-eu.example.com, login-ap.example.com

Authentication latency depends on where your Auth0 tenant is deployed, not on the custom domain name. Choose your tenant’s region based on where your users are located.

Branding and user experience

Keep branding consistent

MCD adds another dimension to your branding efforts. Users expect consistency across all touchpoints:

Universal Login: Customize login pages per domain using domain metadata
Email templates: Use custom domain variables to personalize emails
Error pages: Maintain consistent branding on error pages
Application UI: Match your application’s branding with the authentication experience

For comprehensive guidance, refer to B2B and B2C branding guidelines.

Passkey management

Communicate clearly: Inform users that passkeys are per-domain
Prompt enrollment: Encourage passkey enrollment after the 3rd login
Track enrollment: Monitor which domains users have enrolled passkeys for
Provide help: Offer clear documentation about passkey management

See Passkeys with Multiple Custom Domains for detailed guidance.

User communication

When users interact with multiple custom domains:

Set expectations: Explain that different brands/portals may have different login URLs
Provide guidance: Help users understand which domain to use
Handle errors gracefully: Display clear error messages if users try to access the wrong domain
Support documentation: Maintain clear docs about your domain structure

Operations and maintenance

Monitoring and alerting

Set up monitoring for:

Certificate expiration: Alert 30, 15, and 7 days before expiration
Domain verification status: Monitor for verification failures
Authentication failures: Track failures by custom domain
DNS health: Monitor DNS resolution for all custom domains
API performance: Track Management API latency for domain operations

Documentation

Maintain comprehensive documentation:

Domain inventory: List of all custom domains with metadata and purpose
Application mappings: Which applications use which domains
Runbooks: Procedures for common operations (adding domains, certificate renewal, troubleshooting)
Architecture diagrams: Visual representation of domain structure
Contact information: Responsible teams/individuals for each domain

Testing

Test thoroughly before production:

Functional testing: Verify authentication flows for each custom domain
Integration testing: Test all applications with their assigned custom domains
Email testing: Verify emails use correct custom domains
Failover testing: Test fallback to default domain
Performance testing: Load test authentication through custom domains

Change management

When making changes to custom domains:

Use staging first: Test changes in non-production environments
Gradual rollout: Roll out changes to a subset of domains first
Monitor closely: Watch for issues during rollout
Have rollback plan: Be prepared to revert changes if needed
Communicate changes: Notify stakeholders of planned changes

Common pitfalls to avoid

Don’t over-complicate domain structure

Anti-pattern: Creating a custom domain for every possible variation
Better approach: Start with a few core domains and expand as needed

Don’t forget to update all integration points

When adding new custom domains, update:

Application callback URLs
Social provider redirect URIs
Enterprise connection endpoints
Token validation logic
Monitoring and alerting rules

Don’t neglect documentation

Anti-pattern: Relying on institutional knowledge
Better approach: Document domain assignments, metadata meanings, and operational procedures

Don’t ignore certificate management

Anti-pattern: Letting certificates expire without warning
Better approach: Automate monitoring and renewal processes

Don’t mix authentication contexts

Anti-pattern: Using the same custom domain for unrelated brands/customers
Better approach: Maintain clear separation between different authentication contexts

Brand Customization

Code Customization

Third-Party Customization

Multiple Custom Domains Best Practices

Verify ownership of domains

Planning and architecture

Choose a domain strategy

Configure a default domain

Plan for scale

Use metadata to stay organized

Security

Domain validation in Actions

Organization-based access control

Certificate management

Token validation

Performance

Use regional domains

Branding and user experience

Keep branding consistent

Passkey management

User communication

Operations and maintenance

Monitoring and alerting

Documentation

Testing

Change management

Common pitfalls to avoid

Don’t over-complicate domain structure

Don’t forget to update all integration points

Don’t neglect documentation

Don’t ignore certificate management

Don’t mix authentication contexts

Learn more

Brand Customization

Code Customization

Third-Party Customization

​Verify ownership of domains

​Planning and architecture

​Choose a domain strategy

​Configure a default domain

​Plan for scale

​Use metadata to stay organized

​Security

​Domain validation in Actions

​Organization-based access control

​Certificate management

​Token validation

​Performance

​Use regional domains

​Branding and user experience

​Keep branding consistent

​Passkey management

​User communication

​Operations and maintenance

​Monitoring and alerting

​Documentation

​Testing

​Change management

​Common pitfalls to avoid

​Don’t over-complicate domain structure

​Don’t forget to update all integration points

​Don’t neglect documentation

​Don’t ignore certificate management

​Don’t mix authentication contexts

​Learn more

Verify ownership of domains

Planning and architecture

Choose a domain strategy

Configure a default domain

Plan for scale

Use metadata to stay organized

Security

Domain validation in Actions

Organization-based access control

Certificate management

Token validation

Performance

Use regional domains

Branding and user experience

Keep branding consistent

Passkey management

User communication

Operations and maintenance

Monitoring and alerting

Documentation

Testing

Change management

Common pitfalls to avoid

Don’t over-complicate domain structure

Don’t forget to update all integration points

Don’t neglect documentation

Don’t ignore certificate management

Don’t mix authentication contexts

Learn more