Platform

Custom domains

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

Pointing your domain at Authalla is itself the proof of ownership, and Authalla issues and renews a Let's Encrypt certificate for it 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 - A domain belongs to the first tenant that proves it owns it. Adding a domain on its own reserves nothing, so a domain another tenant added but never proved doesn't stop you

Important constraints:

  • Only one custom domain per tenant is currently supported
  • The domain must not already be proven by another tenant (adding it then fails with a conflict)

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. TXT Record (ownership)

    • Name: _authalla. followed by your custom domain (e.g., _authalla.auth.yourcompany.com)
    • Value: authalla-verification= followed by the token shown in the Admin UI. The token is different for every domain you add
    • Purpose: Proves the domain is yours. Until Authalla finds this record, the domain serves nothing and gets no certificate. Pointing a domain at Authalla isn't enough on its own, because anyone could add a domain whose CNAME already points here

  2. CNAME Record

    • Name: Your custom domain (e.g., auth.yourcompany.com)
    • Value: custom.authalla.com
    • Purpose: Routes traffic to Authalla's infrastructure, so the certificate can be issued

If your DNS provider offers a proxy/CDN toggle for the record, leave it off so the record resolves straight to us. Certificate issuance needs the request to reach Authalla directly.

Example DNS Configuration:

Type    Name                              Value
TXT     _authalla.auth.yourcompany.com    authalla-verification=<token from the Admin UI>
CNAME   auth.yourcompany.com              custom.authalla.com

Once Authalla has found the TXT record, the domain stays verified even if you remove the record later.

3. Wait for Verification

After adding the DNS records:

  1. Status will show as "Pending" - Authalla is waiting for the TXT record and the CNAME to resolve, then requesting the certificate
  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 apps must use the matching issuer/discovery URL. If you switch to a custom domain, update your apps' configuration to use:

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

SSO callback URLs

If you use SSO connections (social or enterprise), 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
  • Passkeys belong to the address they were created on. A passkey created on {tenant-id}.authalla.com isn't offered on your custom domain, so users who created one before the move sign in with their email once and create a new passkey. Add production's custom domain before launch to avoid this.

Each tenant has its own custom domain, so production and staging can use auth.acme.com and auth.stage.acme.com, or domains that aren't related at all, such as auth.acme.dev. See Environments.

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 TXT record is at _authalla.<your domain> with the exact value shown, and that the CNAME value exactly matches custom.authalla.com
  3. The domain was added again - Removing and re-adding a domain gives it a new token, so update the TXT record 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. TXT or CNAME record missing or incorrect - The domain needs the ownership TXT record and a CNAME pointing to custom.authalla.com
  2. DNS propagation issues - Records may not have propagated yet
  3. The record is proxied - A proxy/CDN in front of the record stops the certificate being issued

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

Apps Not Working After Activation

If apps stop working after activating a custom domain:

  1. Update issuer/discovery URL - Apps 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 the apps' 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: Authalla automatically obtains and renews a Let's Encrypt certificate for your custom domain, using the HTTP-01 challenge.

  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. Authalla shows you the CNAME record to add
  3. You add the CNAME record at your DNS provider
  4. Authalla waits for the CNAME to resolve, then requests a Let's Encrypt certificate
  5. Status changes to "Active" once the certificate is serving
Previous
Leaving Authalla
Next
Branding & theming