Custom Domains

Custom domains let you replace the default AuthAction URL with your own branded domain. Instead of users seeing https://acme.eu.authaction.com, they see https://auth.acme.com.

All OAuth 2.0, OpenID Connect, and well-known endpoints work identically on a custom domain, including authorization, token exchange, discovery, and JWKS.

How It Works

1. You add a custom domain (e.g. auth.acme.com) in the AuthAction dashboard.
2. You create a CNAME DNS record pointing your domain to your tenant’s canonical hostname.
3. You verify the domain in the dashboard. AuthAction checks the CNAME record.
4. Once verified, SSL/TLS certificates are provisioned automatically. No manual certificate management is required.
5. All requests to your custom domain are routed to your tenant.

Prerequisites

• A domain you own with access to manage DNS records.
• Your tenant’s canonical hostname, which follows the format:

<tenant>.<region>.authaction.com

For example, if your tenant is acme in the EU region, the canonical hostname is acme.eu.authaction.com.

Setting Up a Custom Domain

Step 1: Add the Domain

1. Open the AuthAction Dashboard.
2. Navigate to Tenant Settings → Custom Domain tab.
3. Click Add Domain.
4. Enter your custom domain (e.g. auth.acme.com) and confirm.

Note

Each tenant can have up to 5 custom domains configured simultaneously. The domain cannot be a subdomain of authaction.com.

Step 2: Create a CNAME Record

In your DNS provider, add a CNAME record:

Type	Name	Target
CNAME	auth.acme.com	acme.eu.authaction.com

Replace the values with your actual domain and tenant hostname. DNS propagation typically takes a few minutes but can take up to 48 hours depending on the provider.

Step 3: Verify the Domain

1. Return to Tenant Settings → Custom Domain.
2. Click the verify icon next to the pending domain.
3. AuthAction performs a DNS lookup to confirm the CNAME points to your tenant’s canonical hostname.
4. Once verified, the domain status changes to Active.

SSL Certificates

After verification, SSL/TLS certificates are automatically issued and renewed for your custom domain. There is no manual step. HTTPS is ready as soon as verification succeeds.

Using Your Custom Domain

Once active, your custom domain is fully interchangeable with the default tenant URL. Update your application’s OAuth configuration to use it:

Endpoint	URL
Authorization	https://auth.acme.com/oauth2/authorize
Token	https://auth.acme.com/oauth2/token
User Info	https://auth.acme.com/oauth2/userinfo
Discovery	https://auth.acme.com/.well-known/openid-configuration
JWKS	https://auth.acme.com/.well-known/jwks.json

Well-Known Endpoint Responses

The OpenID Connect discovery document (/.well-known/openid-configuration) adapts its endpoint URLs based on the domain used in the request, with one important exception: the issuer always remains your tenant’s canonical AuthAction domain.

When accessed through your custom domain, the response looks like this:

{
  "issuer": "https://acme.eu.authaction.com/",
  "authorization_endpoint": "https://auth.acme.com/oauth2/authorize",
  "token_endpoint": "https://auth.acme.com/oauth2/token",
  "userinfo_endpoint": "https://auth.acme.com/oauth2/user",
  "jwks_uri": "https://auth.acme.com/.well-known/jwks.json"
}

Notice that issuer points to acme.eu.authaction.com (the canonical tenant domain), while all other endpoint URLs use the custom domain (auth.acme.com). This means tokens are always issued with the canonical tenant domain as the iss claim, regardless of which domain the user interacted with. Your application should validate the iss claim against the canonical tenant domain.

Removing a Custom Domain

1. Navigate to Tenant Settings → Custom Domain.
2. Click the delete icon next to the domain you want to remove.
3. Confirm the removal.

Caution

Removing a custom domain takes effect immediately. Any applications configured to use that domain will no longer be able to reach your tenant through it. Update your application configuration before removing a domain.

Multiple Custom Domains

You can configure up to 5 custom domains per tenant. Each domain operates independently and all are active simultaneously once verified. This is useful when you need different branded login URLs for different products or audiences that share the same tenant.

Troubleshooting

Problem	Solution
Verification fails	Confirm the CNAME record is correct and DNS has propagated. Use dig auth.acme.com CNAME or an online DNS checker.
SSL certificate not issued	Certificates are issued automatically after verification. Allow a few minutes. If the issue persists, re-verify the domain.
Domain shows “Pending”	The CNAME record may not have propagated yet. Wait and retry verification.
”Domain cannot be a subdomain of authaction.com”	Custom domains must be on your own domain, not a subdomain of the AuthAction platform domain.