Hanko Custom Domain Guide:About Hanko:Hanko is a modern open source authentication solution and the fastest way you integrate passkeys, 2FA, SSO, and more—with full control over your data. Move between self-hosted and Hanko Cloud anytime. No lock-in. Just Auth how it should be: secure, user friendly, and fully yours.What This Guide Covers: This guide demonstrates how to configure a custom domain for your Hanko project. You’ll learn to set up DNS records, configure SSL certificates, and update your applications to use your branded authentication domain.Key Technologies:
- DNS Management (CNAME Records)
- SSL/TLS Certificates
- Domain Configuration
- Hanko Cloud Console
- Active Hanko Cloud project
- Domain name that you control
- Access to your domain’s DNS settings
- Basic understanding of DNS configuration
- Set up CNAME record in your DNS configuration
- Configure custom domain in Hanko Console
- Verify SSL certificate provisioning
- Update OAuth provider redirect URLs
- Modify application API endpoints
- Test authentication flows with custom domain
Setting up a custom domain for your Hanko project
This guide explains the benefits of using a custom domain with Hanko and walks you through the configuration process.Why use a custom domain?
Using a custom domain for your Hanko authentication project provides several important advantages:-
Better compatibility with 3rd-Party OAuth providers
With OAuth providers, the redirect URL or redirect domain is displayed on the user’s consent screen. Using a custom domain means that your own domain/URL (e.g.,
auth.yourapp.com) will be shown instead of the default Hanko domain (hanko.io). - 3rd-Party cookie tracking prevention Some modern browsers block 3rd-party cookies by default. A custom domain allows cookies to belong to your domain and work reliably in these browsers.
- Google verified app features: If using Google OAuth, having a custom domain allows your application to display your app’s logo and leverage other branding features (e.g., custom scopes). (See Google Documentation for more info)
How to set up a custom domain
To set up your custom domain for authentication, follow these steps:-
Create a CNAME record in your DNS configuration:
Configure a CNAME record in your domain’s DNS settings to point to
cname.hanko.io
The process for this varies by DNS provider, but most providers will have instructions to follow. Here are links to
updating the appropriate DNS records for some popular providers:
- Configure the custom domain in the Hanko Console:
- Log in to the Hanko Console.
- Navigate to Project settings > Custom domain.
- Enter your custom domain (e.g.,
auth.yourapp.com) in the input field and save.
After setting up the custom domain, please allow a few minutes for the changes to propagate through the DNS system before they take effect.When the custom domain is set up, your project will no longer be reachable through the previous API URL.
Updating Your application for the custom domain
After setting up the custom domain, you’ll need to update your application’s configuration to use the new URLs across various places:- Change your API URL: After setting up the custom domain, update the API URL in your Hanko Elements configuration or frontend-sdk initialization, and in your backend code.
-
Update redirect URLs:
- If you’re using 3rd-party connections (e.g., Google, SAML), ensure that all redirect URL configurations are updated.
- Retrieve the new redirect URL from the Project Settings > Social connections and Project settings > Enterprise connections
- Update these URLs in your 3rd-party provider configurations (e.g., Google, Azure AD).