Features
Domain Management

Domain Management

Custom domains allow you to use your own domain (like auth.yourcompany.com) instead of the default Skycloak URLs. This provides a professional appearance and maintains brand consistency for your users.

Domain configuration page

Why Use Custom Domains?

Custom domains provide several benefits:

  • Brand Consistency: Users see your domain throughout the authentication process
  • Trust & Security: Users recognize and trust your domain
  • Professional Appearance: No third-party branding in URLs
  • SEO Benefits: Better for search engine optimization if you have public-facing auth pages
  • Compliance: Some regulations require data to appear to come from your domain

Setting Up Your Custom Domain

Step 1: Access Domain Settings

  1. Navigate to the Domain section in your Skycloak dashboard
  2. Click on “Configure Domain” to start the setup process

Step 2: Add Your Domain

  1. Enter your desired domain (e.g., auth.yourcompany.com)
  2. Choose the authentication type:
    • Subdomain: Recommended for most use cases (e.g., auth.yourcompany.com)
    • Path-based: Use a path on your main domain (e.g., yourcompany.com/auth)

Step 3: Configure DNS Records

After adding your domain, you’ll need to configure your DNS settings:

  1. Add a CNAME Record:

    Type: CNAME
Name: auth (or your chosen subdomain)
Value: app.skycloak.io.cdn.cloudflare.net
TTL: 3600 (or your preference)

  2. Verify DNS Propagation:

    • DNS changes can take 15 minutes to 48 hours to propagate
    • Use tools like dig or nslookup to verify:
    dig auth.yourcompany.com

Step 4: SSL Certificate Setup

Skycloak automatically provisions SSL certificates for your custom domain using Cloudflare for SaaS:

  1. Once DNS is configured, click “Verify Domain”
  2. Skycloak will automatically:
    • Verify domain ownership via Cloudflare
    • Generate SSL certificates through Cloudflare’s infrastructure
    • Configure HTTPS with global CDN support
    • Enable DDoS protection and performance optimization

Step 5: Update Your Applications

After domain setup, update your applications to use the new domain:

  1. Update Redirect URIs in your application settings
  2. Update OAuth endpoints in your application code
  3. Test the authentication flow with the new domain

Domain Configuration Options

Primary Domain Settings

  • Domain Name: Your custom domain (e.g., auth.yourcompany.com)
  • SSL Certificate: Automatically managed by Skycloak
  • Force HTTPS: Always enabled for security
  • HSTS: HTTP Strict Transport Security enabled by default

Advanced Settings

  • Custom Headers: Add security headers like CSP
  • Cookie Settings: Configure cookie domain and security settings
  • CORS Configuration: Set allowed origins for your applications

Multiple Domains

Depending on your plan, you can configure multiple custom domains:

  • Developer: 1 custom domain
  • Launch: 1 custom domain
  • Business: 1 custom domain (additional domains available as add-ons)
  • Enterprise: 5 custom domains (additional available)

Use cases for multiple domains:

  • Different brands or products
  • Staging vs. production environments
  • Regional domains for global applications

Troubleshooting Domain Setup

Common Issues

  1. Domain Verification Failed

    • Ensure DNS records are properly configured
    • Wait for DNS propagation (up to 48 hours)
    • Check for typos in the CNAME record

  2. SSL Certificate Error

    • Verify domain ownership
    • Ensure no CAA records blocking Let’s Encrypt
    • Contact support if issues persist

  3. Domain Not Loading

    • Clear browser cache and cookies
    • Check DNS resolution: nslookup auth.yourcompany.com
    • Verify the domain is active in Skycloak dashboard
    • Ensure CNAME points to app.skycloak.io.cdn.cloudflare.net

DNS Provider Examples

Cloudflare

  1. Log into Cloudflare dashboard
  2. Select your domain
  3. Go to DNS settings
  4. Add CNAME record pointing to app.skycloak.io.cdn.cloudflare.net
  5. Keep proxy enabled (orange cloud) for best performance

Route 53 (AWS)

  1. Open Route 53 console
  2. Select your hosted zone
  3. Create new record set
  4. Choose CNAME type
  5. Point to app.skycloak.io.cdn.cloudflare.net

GoDaddy

  1. Access DNS Management
  2. Add new CNAME record
  3. Enter subdomain and target

Security Considerations

When using custom domains:

  • Always use HTTPS: Skycloak enforces HTTPS for all custom domains
  • HSTS Headers: Automatically applied to prevent downgrade attacks
  • Certificate Renewal: Fully automated by Cloudflare
  • Domain Validation: Continuously verified via Cloudflare
  • DDoS Protection: Built-in protection via Cloudflare’s global network
  • WAF Rules: Optional Web Application Firewall rules available

Best Practices

  1. Use Subdomains: Easier to manage than path-based routing
  2. Plan Domain Structure: Consider your application architecture
  3. Document DNS Changes: Keep records of your DNS configuration
  4. Test Thoroughly: Verify all authentication flows after setup
  5. Monitor Certificate Expiry: Although automated, monitor for issues

Realm Domain Mapping

Realm domain mapping allows you to assign specific custom domains to individual realms within your Keycloak cluster. This provides isolated authentication experiences for different applications or tenants.

Key Features

  • Realm Isolation: Each realm can have its own dedicated domain
  • Multi-tenancy Support: Perfect for SaaS applications with multiple tenants
  • CORS Configuration: Configure allowed origins per realm mapping
  • Automatic SSL: SSL certificates are automatically managed for each domain

Setting Up Realm Mapping

  1. Prerequisites:

    • Have at least one verified custom domain configured
    • Identify which realms need dedicated domains

  2. Create a Realm Mapping:

    • Navigate to the Domain page in your cluster
    • Expand the “Realm Domain Mappings” section
    • Click “Add Realm Mapping”
    • Select the realm and domain to map
    • Choose Admin Console Access: Enable or disable access to the Keycloak admin console through the custom domain
    • Optionally configure CORS allowed origins
    • Click “Create Mapping”

  3. Access Your Realm: After mapping, your realm will be accessible at:

    https://[custom-domain]/realms/[realm-name]/account
https://[custom-domain]/realms/[realm-name]/protocol/openid-connect/auth

Admin Console Access Control

You now have full control over admin console access for each realm mapping:

  • Admin Access Enabled (default): Admin console is accessible at https://[custom-domain]/admin/[realm-name]/console
  • Admin Access Disabled: Admin console is only accessible through your original Skycloak domain

This provides flexibility in security boundaries - you can restrict admin access to your main Skycloak domain while allowing end-user authentication through custom domains.

Managing Admin Access

To Enable Admin Access:

  1. Go to your Domain page in the cluster
  2. Find the realm mapping in the table
  3. Toggle the “Admin Access” switch to “Enabled”
  4. The admin console will be accessible at: https://[custom-domain]/admin/[realm-name]/console

To Disable Admin Access:

  1. Toggle the “Admin Access” switch to “Disabled”
  2. Admin console will only be accessible via: https://[cluster-id].[region].skycloak.io/admin

Example

If your cluster URL is https://abc123.us.skycloak.io and you map auth.example.com to the realm production:

With Admin Access Enabled:

  • ✅ Realm access: https://auth.example.com/realms/production/account
  • ✅ Admin console: https://auth.example.com/admin/production/console
  • ✅ Admin console (original): https://abc123.us.skycloak.io/admin

With Admin Access Disabled:

  • ✅ Realm access: https://auth.example.com/realms/production/account
  • ❌ Admin console: https://auth.example.com/admin/production/console (will return 403 Forbidden)
  • ✅ Admin console: https://abc123.us.skycloak.io/admin (use this instead)

Use Cases

Multi-tenant SaaS Applications:

  • Map tenant1.auth.com → tenant1 realm
  • Map tenant2.auth.com → tenant2 realm
  • Each tenant gets their own branded authentication

Environment Separation:

  • Map auth.staging.com → staging realm
  • Map auth.production.com → production realm

Brand Separation:

  • Map auth.brand1.com → brand1 realm
  • Map auth.brand2.com → brand2 realm

Troubleshooting

403 Forbidden Error When Accessing Admin Console:

  • Cause: Trying to access /admin through a realm-mapped custom domain
  • Solution: Use your original *.skycloak.io domain for admin access

Realm Not Accessible:

  • Ensure the domain is verified and SSL certificate is active
  • Check that the realm name is correct in the URL
  • Verify DNS records are properly configured

CORS Issues:

  • Add your application’s origin to the CORS allowed origins when creating the mapping
  • Update the mapping if you need to add additional origins

Integration with Email Branding

Custom domains work seamlessly with email branding:

  • Email links will use your custom domain
  • Consistent branding across all touchpoints
  • Better email deliverability with matching domains

See Email Configuration for more details.

Next Steps

Security LogsEmail Configuration