Custom Domains in Okta
How to put your own web address on your sign-in page, what happens behind the scenes when you do, and how to set it up without breaking anyone's login.
Picture a company called Northwind Retail. It has 12,000 employees, a few hundred partner stores, and a handful of internal apps. Every morning, all of those people land on a sign-in page. In the address bar they see something like northwind.okta.com. It works fine. But one day the security team gets a report: a staff member almost typed their password into a fake page that looked exactly like the real one. The fake page lived at northwind-okta-login.com. The staff member could not tell the difference, because the real address also ended in a name that was not Northwind’s own.
This is the exact problem custom domains in Okta solve. A custom domain lets your sign-in page live at an address you own, such as login.northwind.com. Your users see your name. Your security team can give one simple rule: “Only ever sign in at login.northwind.com.” And your apps, cookies, emails, and tokens can all line up under that one trusted name.
In this guide, we start from zero. We explain what every term means, how the pieces fit together, what happens inside when you switch it on, and what can go wrong. By the end, you will understand custom domains in Okta well enough to plan one, run one, and explain it to someone else.
1Why Your Sign-In Page Has Someone Else’s Name On It
Before we talk about the fix, we need to understand the starting point: what Okta gives you by default, and why that default is not always what a company wants.
What Okta Is, in Plain Words
Okta is an identity provider, often shortened to IdP. An identity provider is a service that keeps track of who people are and checks their proof of identity, such as a password or a fingerprint, so that other apps do not have to. When you click “Sign in with your company account” on an app, that app sends you to the identity provider. The identity provider checks you, then sends you back to the app with a note saying “yes, this is really Maria from accounting.”
The big idea is simple. Instead of every app having its own username and password box, there is one trusted front door. This is called single sign-on, or SSO. Companies like Netflix, Amazon, and Uber all use some form of central identity to manage who can get into which internal system. Okta is one of the most widely used products for doing this.
The Default Address
When a company signs up for Okta, it gets its own private space inside Okta. This space is called an org, which is short for organization. You can think of it as your own apartment inside a very large apartment building. Okta gives that apartment an address. It looks like yourcompany.okta.com. We will call this the Okta domain or the org URL.
Every Okta customer starts with an address like this. It is free, instant, and works right away. For a test or a small team, it is perfectly fine.
The Problem With the Default
The default address has three weaknesses once you grow.
- It is not your brand. Your customers and employees see a name that is partly Okta’s. It feels like a visit to a stranger’s website.
- It is hard to teach. Security training works best when the rule is short. “Only trust addresses ending in our company name” is easy. “Only trust our special okta.com address, but not any other okta.com address” is confusing.
- It limits what you can customize. Some of the deeper Okta features, such as fully changing the HTML of the sign-in page and the error pages, need a custom domain before they will turn on.
Think of a food stall inside a big shopping mall. The mall gives every stall a small sign that says “Stall 42, Level 2.” It works, but customers cannot easily find you outside the mall, and the sign says nothing about your brand. A custom domain is like putting up your own big signboard with your own shop name, in your own fonts, so people know exactly where they are. The stall is still inside the mall, and the mall still does the electricity and security, but the name on the front is yours.
Big Companies Already Do This
If you look at the biggest websites in the world, you will notice they almost never send you to a generic address to sign in. Google uses accounts.google.com. Microsoft uses login.microsoftonline.com. Amazon Web Services uses signin.aws.amazon.com. GitHub puts its sign-in page under github.com/login. Each of these is a name the company owns. Users learn it, trust it, and can spot a fake more easily.
A custom domain in Okta gives your company the same advantage, even though the engine behind the page is Okta’s.
A custom domain does not move your Okta data out of Okta. Your users, groups, policies, and apps stay exactly where they were. Only the front-door address changes.
2Core Concepts: The Words You Need First
Custom domains sit where three worlds meet: web addresses, encryption, and identity. Each world has its own vocabulary. Here are the terms we will use for the rest of the guide, explained one at a time.
DNS: The Internet’s Phone Book
DNS stands for Domain Name System. Computers talk to each other using numbers called IP addresses, but people prefer names like northwind.com. DNS is the giant phone book that turns names into numbers. When you type a name into your browser, your computer asks a DNS server, “What number belongs to this name?” The server answers, and the browser connects.
Every company that owns a name also owns a DNS zone. A zone is just the page in the phone book that you control. Inside it, you can add lines called records. A custom domain in Okta needs you to add two records to your zone.
TXT record
A short note attached to a name. Okta gives you a secret value, and you publish it. When Okta can see it, Okta knows you really control the domain. It is like writing a code word on your shop wall so the inspector knows the shop is yours.
CNAME record
An alias. It says “when someone asks for this name, go and use that other name instead.” You point your sign-in hostname at an Okta target name. It is like a sign on your shop door that says “For orders, go to the warehouse next door.”
Subdomain
A front part added to your main name. In login.northwind.com, the word login is the subdomain. Custom domains in Okta are normally set up on a subdomain, not on the bare main name.
TLS certificate
A digital ID card for a website. It proves “this server really is login.northwind.com” and lets the browser set up an encrypted connection. Without it, browsers show scary warnings. This is the padlock in the address bar.
Certificate authority
The trusted organization that issues certificates, like a passport office. Browsers come with a built-in list of authorities they trust. Let’s Encrypt is one well-known free authority.
Org (tenant)
Your private space inside Okta, holding your users, apps, and rules. People also call it a tenant. The default address of the org is the Okta domain.
Brand
A bundle of look-and-feel settings: logo, colors, sign-in page layout, email templates. Okta lets you attach a custom domain to a brand, so different brands can show different addresses.
Issuer
The name an authorization server stamps on the tokens it creates, like a bank’s name printed on a cheque. Apps check the issuer to make sure a token came from a source they trust.
SNI and the Host Header
Many websites can share the same servers and the same IP addresses. So when your browser connects, it must tell the server which website it wants. It does this twice. First, during the encryption handshake, it sends the name using a feature called Server Name Indication, or SNI. This lets the server pick the right certificate. Second, once the connection is up, it sends a Host header inside the request, which lets the server route the request to the right customer. Okta’s front end uses both to find your org when someone visits login.northwind.com.
Imagine a huge office tower with one reception desk. A visitor walks in and says the company name out loud. That is SNI, because the receptionist knows which ID badge style to expect. Then the visitor hands over a written note with the company name and the person they are meeting. That is the Host header, because it tells the receptionist which floor to send them to. One building, one desk, thousands of companies.
Session Cookies and Why the Domain Matters
A cookie is a small piece of data a website stores in your browser. After you sign in, Okta stores a session cookie so it can remember you are already signed in. Cookies are tied to the domain that set them. A cookie set by northwind.okta.com belongs to Okta’s domain. A cookie set by login.northwind.com belongs to Northwind’s domain. This difference becomes very important in Chapter 7, because modern browsers treat cookies from “another site” much more strictly than cookies from “your own site.”
Okta’s custom domain feature is for the Okta Workforce and Customer Identity products that use the Okta org URL. Auth0, which is a separate product owned by Okta, has its own custom domain feature with different steps. If you search the web for help, make sure the instructions match the product you are using.
3Architecture and Components
A custom domain is really a small team of parts working together: your DNS, Okta’s front door, a certificate, and your org. Let us meet each part and then see the whole picture.
The Parts
There are six main players. Four of them are on Okta’s side, and two are on yours.
| Component | Who owns it | What it does |
|---|---|---|
| Your DNS zone | You | Holds the TXT and CNAME records that prove ownership and send traffic to Okta. |
| Domain registration | You | Your right to use the main name, such as northwind.com. Without this, nothing else works. |
| Okta edge (front door) | Okta | Receives the connection, picks the certificate by SNI, and routes by Host header. |
| Certificate store | Okta | Holds the certificate and private key for your hostname, whether Okta created them or you uploaded them. |
| Your org | You, hosted by Okta | Runs the sign-in logic, policies, multi-factor checks, and token creation. |
| Brand and sign-in page | You, hosted by Okta | Controls the look of pages and emails shown under your custom hostname. |
The Whole Picture
The diagram below shows what happens when a user opens your custom hostname. Read it left to right. The user’s browser asks DNS where to go. DNS says “follow this alias to Okta.” The browser then connects to Okta’s front door, which finds your org and serves your sign-in page.
flowchart LR
U["User Browser"] --> R["DNS Resolver"]
R --> Z["Your DNS Zone: login.northwind.com CNAME record"]
Z --> E["Okta Edge: TLS and Host routing"]
U --> E
E --> C["Certificate Store"]
E --> O["Northwind Okta Org"]
O --> B["Brand and Sign-in Page"]
O --> P["Policies and MFA"]
O --> T["Token Service"]
T --> A["Application"]
Notice that your DNS zone only plays a small role. It does not carry the traffic itself. It just points the way. After the first lookup, everything happens inside Okta. That is good news for you: you do not need to run servers, load balancers, or certificates yourself.
Separation of Duties
This design splits the work cleanly. You own the name and the DNS. Okta owns the machines, the encryption endpoints, and the high availability. If Okta adds more servers or moves traffic between data centers, your CNAME still points to the same Okta target name, and Okta handles the rest behind it.
Production example: a retailer with a sign-in front door
A large online retailer with millions of shoppers wants customers to sign in at an address under its own name. It adds a custom domain for the customer-facing sign-in. The retailer’s DNS team adds two records, the identity team picks the certificate option, and the web team keeps their existing site on a different hostname. Nothing about the shopping site changes. Only the login hostname moves under the brand.
Your custom domain is a front door, not a second house. All custom-domain traffic lands in the same org as the default Okta address. Your policies, users, and logs are not duplicated.
4How Setup Works Internally
Setting up a custom domain takes about an hour of hands-on work, but it has a very specific order. Each step exists for a reason. Knowing the reason helps you fix things when they go wrong.
The Seven Steps
Choose the hostname
Pick a subdomain you control, such as login, sso, or id. Choose something short, stable, and easy to say out loud. You will be teaching this name to every user, so avoid names that you might regret in two years.
Add the domain in the Okta Admin Console
In the Admin Console, open the Customizations area and find the domain settings. Enter your hostname. Okta checks that the name is well formed and not already in use by another Okta org.
Choose the certificate mode
Pick Okta-managed or bring your own. We compare them in detail in Chapter 5. If you choose to bring your own, you upload the certificate, its private key, and the chain of intermediate certificates at this stage.
Publish the TXT record
Okta shows you a record name and a secret value. You add that TXT record to your DNS zone. This proves you control the domain. Without this proof, anyone could claim anyone else’s name.
Verify
Back in the Admin Console, you click verify. Okta looks up your TXT record in public DNS. If it sees the right value, the domain is marked as verified. If DNS has not caught up yet, you wait and try again.
Publish the CNAME record
Okta now shows you a target name. You add a CNAME record from your hostname to that target. This is the record that actually sends browsers to Okta’s front door. With an Okta-managed certificate, this record is also part of how Okta proves control to the certificate authority.
Certificate issued and domain goes live
For Okta-managed mode, Okta requests the certificate and installs it. For bring-your-own mode, your uploaded certificate is activated. Once the status shows ready, the hostname starts serving your org’s pages.
Why Two Records and Not One?
This question confuses many beginners. The TXT record answers “do you own this name?” The CNAME record answers “where should traffic for this name go?” These are different jobs. Ownership proof must come first, because without it, Okta should never agree to serve a name for you. Routing comes second, because routing without ownership proof would allow someone to point a name they do not own at Okta and cause confusion.
When you register for a new library card, the librarian first checks your ID. That is the TXT record: proof that you are who you say you are. Only after that does the librarian give you a card that routes your borrowing to your account. That is the CNAME record: it connects your name to the service. Showing the card without the ID check would be unsafe. Showing the ID without getting the card would be useless.
The Setup Flow at a Glance
flowchart TD
S["Start: choose hostname"] --> A["Add domain in Okta Admin Console"]
A --> M{"Certificate mode?"}
M -->|"Okta-managed"| T["Publish TXT record"]
M -->|"Bring your own"| U["Upload certificate, key and chain"]
U --> T
T --> V["Verify ownership"]
V -->|"Not found yet"| W["Wait for DNS and retry"]
W --> V
V -->|"Verified"| N["Publish CNAME record"]
N --> I["Certificate issued or activated"]
I --> L["Domain is live"]
Common Delays
The most common reason setup stalls is DNS timing. When you add a record, it does not appear everywhere in the world at once. DNS servers keep copies of answers for a time called the TTL, short for time to live. If a record was cached as “does not exist” a few minutes ago, some servers will keep saying so until that copy expires. The fix is patience, plus a low TTL on the records you are about to add. Many teams lower the TTL a day before the change so any later fix can spread quickly.
If your company uses CAA records, which are DNS records that list which certificate authorities may issue certificates for your name, make sure the authority Okta uses is allowed. Otherwise the certificate request will be refused, and the error may look confusing at first glance.
5Certificates: Okta-Managed or Bring Your Own
The biggest decision in a custom domain project is who looks after the certificate. This one choice decides how much work you do every few months for as long as the domain exists.
Option A: Okta-Managed Certificate
In this mode, Okta asks a certificate authority for a certificate on your behalf. Okta uses Let’s Encrypt for this. Okta stores the private key, installs the certificate, and renews it before it runs out. You do not upload anything. You only keep the DNS records in place.
Certificates from this authority are short-lived on purpose, about ninety days at the time of writing. Short life means a stolen certificate is useful to a thief for only a short time. It also means renewal must be automatic, because no human wants to do this every few weeks. Okta’s automation handles it.
Option B: Bring Your Own Certificate
In this mode, you buy or create a certificate yourself, then upload three things to Okta: the certificate, the matching private key, and the certificate chain. The chain is the set of intermediate certificates that connects your certificate back to a root authority that browsers trust. You are responsible for renewing and re-uploading before the certificate expires. Okta can warn you by email, but it cannot make the new certificate for you.
Teams choose this mode when their security rules say that every certificate must come from a specific authority, when they use extended validation or special certificate policies, or when they need to reuse a wildcard certificate across many services.
Okta-managed: strengths
- Renewal is automatic, so no surprise expiry outage.
- No private key ever sits on a laptop or in a shared folder.
- Fastest to set up. Two DNS records and you are done.
- Less paperwork and no purchase request.
Okta-managed: limits
- You cannot choose the certificate authority.
- Renewal depends on the CNAME record staying in place.
- A restrictive CAA record can block issuance.
- Some strict compliance programs insist on their own authority.
Bring your own: strengths
- You pick the authority and the certificate type.
- Fits strict internal certificate policies.
- You control the exact renewal date.
Bring your own: limits
- You must renew and upload on time, every time.
- A missed renewal causes a sign-in outage on your hostname.
- You must protect the private key during upload and storage.
- Certificate lifetimes are getting shorter across the industry, so the manual work keeps growing.
The Shrinking Certificate Lifetime
The rules for publicly trusted certificates are changing. The industry body that sets these rules, called the CA/Browser Forum, agreed to reduce the maximum lifetime step by step. As of this writing, the maximum is about 200 days. It is scheduled to drop to about 100 days in 2027 and to about 47 days in 2029. For a team that renews by hand once a year today, this schedule means renewing many times a year soon. This change is a strong reason to prefer automatic renewal wherever you can.
How the Two Modes Differ in Flow
flowchart LR
subgraph OM["Okta-managed"]
direction TB
A1["CNAME and TXT in place"] --> A2["Okta requests certificate"]
A2 --> A3["Okta installs certificate"]
A3 --> A4["Okta renews automatically"]
A4 --> A2
end
subgraph BY["Bring your own"]
direction TB
B1["You obtain certificate"] --> B2["You upload certificate, key, chain"]
B2 --> B3["Okta serves it"]
B3 --> B4["You renew before expiry"]
B4 --> B2
end
Okta-managed is like a gym membership that renews itself on your card every month. You never think about it, but if you cancel the card, the membership stops. Bring your own is like buying a yearly pass at the front desk. You get to choose the pass, but if you forget the date, you walk up to a locked door.
With Okta-managed certificates, never delete the CNAME record “to clean up DNS.” Okta needs it to keep renewing. Removing it is a quiet change that looks harmless on the day and breaks sign-in weeks later when the certificate runs out.
6Data Flow: What Happens When Someone Signs In
Now let us follow one real sign-in from the first click to the final redirect. This is the lifecycle of a request through a custom domain.
Step by Step
Say Maria opens the expense app. The app does not know who she is, so it sends her browser to your custom hostname. A lot happens in the next second or two.
The app redirects Maria
The app sends her browser to the authorize address on login.northwind.com, with details about which app is asking and where to send her back.
DNS lookup
Her browser asks DNS about login.northwind.com. DNS follows the CNAME alias to Okta’s target and returns Okta’s front-door address.
Encrypted connection
The browser connects and sends the hostname through SNI. The edge picks the certificate for login.northwind.com. The browser checks it and shows the padlock.
Routing to the org
Through the Host header, the edge identifies Northwind’s org, applies the right brand, and returns the sign-in page with your logo and colors.
Authentication
Maria enters her password and approves a multi-factor prompt. Okta checks your policies. Okta then sets a session cookie, scoped to login.northwind.com.
Back to the app
Okta sends her browser back to the expense app with a short-lived code. The app exchanges the code for tokens and checks that the issuer matches what it expects.
sequenceDiagram
participant M as Maria Browser
participant X as Expense App
participant D as DNS
participant E as Okta Edge
participant O as Northwind Org
M->>X: Open app
X-->>M: Redirect to login.northwind.com
M->>D: Where is login.northwind.com
D-->>M: Alias to Okta target and address
M->>E: TLS handshake with SNI
E-->>M: Certificate for login.northwind.com
M->>E: Request with Host header
E->>O: Route to Northwind org
O-->>M: Sign-in page with brand
M->>O: Password and MFA
O-->>M: Session cookie and redirect with code
M->>X: Return with code
X->>O: Exchange code for tokens
O-->>X: Tokens with issuer
Where Time Is Spent
For the user, the extra DNS alias adds a very small amount of time on the first visit, and nothing afterwards because answers are cached. The encryption handshake and the authentication steps themselves cost the same as on the default address. In other words, a custom domain should not make sign-in feel slower. If it does, look at DNS caching and the network path first.
Everything in this flow also works for the default Okta address. A custom domain does not change how authentication works. It changes which name users and apps see.
7What Changes After You Turn It On
Turning on a custom domain feels like a small change, but it touches many places. Think of it as renaming the front door of a building. The rooms inside stay the same, but every map, sign, and delivery address that mentions the door needs a second look.
Sign-in and error pages
Your sign-in page, password reset pages, and error pages now appear under the custom hostname. This is also what unlocks the deeper customization, such as editing the full page HTML, which the default address does not allow.
Issuer in tokens
Authorization servers let you choose whether tokens carry the Okta address or the custom address as the issuer. If you change it, the issuer value in every new token changes too. Every app and API that validates tokens must be updated to expect the new value.
Single sign-on URLs
SAML apps use sign-in and sign-out addresses taken from your org. Apps set up before the change may hold the old address. Plan to review each one. The old Okta address usually keeps working for a while, but you should not depend on that forever.
First-party session
The session cookie now belongs to your own domain family. When your apps live on the same main name, browsers treat Okta’s cookie as “from your own site.” This matters a lot for silent sign-in checks that run inside hidden frames.
Admin Console address
Administrators usually keep using a separate Okta admin address, not the custom hostname. Check the current Okta documentation for your plan, because this area has changed over time. Keep a break-glass path that does not depend on your own DNS.
Okta Verify and device features
Okta Verify and passwordless features may be tied to your org’s address. After enabling a custom domain, test enrollment and sign-in on real devices before announcing it widely.
Why First-Party Cookies Matter
Browsers such as Safari and Firefox have limited cookies that come from “another site” for years, and Chrome has moved in the same direction with new privacy tools. A site is called third-party when a page on one name loads something from a different main name. If your app lives on app.northwind.com and Okta is on northwind.okta.com, Okta’s session cookie is third-party in a hidden frame. Browsers may block it, and silent sign-in checks fail. When Okta is on login.northwind.com, both names share the same main name, and the cookie is treated as first-party. Silent checks work far more reliably.
The Old Address Does Not Vanish
After you enable a custom domain, the original Okta address of your org normally still works. This is helpful during migration, because nothing breaks the second you turn the feature on. But it can also be a hidden risk. If users still bookmark the old address, your “only trust our hostname” rule is weaker than you think. Plan a time to move bookmarks, app settings, and training material over, and consider whether your plan lets you restrict use of the older address.
Production example: a software company with many apps on one main name
A software company runs its customer dashboard, its billing portal, and its support site under the same main name. After moving Okta to a sign-in hostname under that name, hidden-frame session checks in the dashboard stop failing in Safari. Support tickets about “random sign-out” drop, because the cookie is now first-party for every app on that main name.
Make a list of every place that contains your Okta address: SAML apps, OIDC redirect settings, API clients, mobile apps, documentation, bookmarks, and help desk scripts. This list is your migration checklist.
8Tokens and Federation in Depth: OIDC and SAML
Chapter 7 told you that issuer values and sign-in addresses can change. This chapter slows down and explains exactly why, so you can predict which of your apps will notice the change and which will not.
A Quick Refresher on the Two Main Languages
When an app asks Okta to sign a person in, the two sides need a shared language. Two languages are common. OpenID Connect, called OIDC, is a modern language built on top of OAuth 2.0. It uses short text packages called tokens, and it is popular with web apps, mobile apps, and APIs. SAML, which stands for Security Assertion Markup Language, is an older language that passes signed XML documents between the identity provider and the app. It is still very common in business software.
Both languages rely on the same idea: the app trusts a named issuer, and it checks that what arrives was really created by that issuer. The name of the issuer, and the addresses where the issuer can be reached, are what a custom domain touches.
What an App Checks in an OIDC Token
Most OIDC tokens are JSON Web Tokens, or JWTs. A JWT is a small package with three parts: a header, a set of claims, and a signature. The claims are facts, such as who the user is, which app the token is for, and when it expires. A careful app or API checks at least four things before it believes a token.
Signature
The app fetches the public signing keys from a published key list and checks that the signature matches. This proves nobody changed the token on the way.
Issuer
The token carries an issuer claim. The app compares it with the issuer it was configured to trust. If they do not match exactly, the token is rejected. This is the check that a custom domain can affect.
Audience
The token names who it is meant for. An API should only accept tokens meant for that API. This stops a token for one service from being used on another.
Time
Tokens expire. The app checks that the token has not run out of time and was not issued in the future. Small clock differences between machines are allowed for.
Where the Custom Domain Shows Up
An OIDC app is told about its identity provider through a few addresses: the authorize address where users are sent, the token address where codes are exchanged, the key list address, and the issuer string. Many apps learn all of these from a single discovery document, a public page at a well-known path under the issuer. The document lists every address the app needs. When the issuer is the custom hostname, the discovery document, and every address inside it, use the custom hostname.
What does not change is the app’s own address list. The redirect URI is the address in your app where Okta sends the user back after sign-in. It belongs to your app, so it stays the same. A common beginner worry is “do I need to change all my redirect addresses?” The answer is no. You change what the app knows about Okta, not what Okta knows about the app.
| Item | Belongs to | Changes with a custom domain? |
|---|---|---|
| Redirect URI | Your app | No |
| Authorize and token addresses | Okta | Yes, if the app is moved to the custom hostname |
| Issuer string in tokens | Authorization server | Yes, if you choose the custom address as issuer |
| Public key list address | Okta | Yes, follows the issuer |
| Client ID and secret | Your app and Okta together | No |
| Scopes and claims | Authorization server | No |
| Trusted origins list | Okta org | No, but check it if your browser app calls Okta directly |
Embedded Sign-In Widgets
Some teams do not send users to an Okta-hosted page at all. Instead, they place Okta’s sign-in widget directly inside their own page. This widget is a piece of code that talks to Okta behind the scenes. It is set up with a base address that points to the org. If you move to a custom domain, you should update that base address so the widget talks to the custom hostname. Otherwise the widget keeps using the default address, and you will see the same third-party cookie problems that you were trying to escape.
Two Ways to Roll Out the Issuer Change
Big switch
- One planned window, one change.
- Simple to explain and to test.
- Works for small estates with few validators.
Big switch: risk
- If one validator is missed, users see failures at once.
- Rollback means switching every system back.
- Hard to coordinate across many teams.
New authorization server for the new issuer
- Teams move one API at a time at their own pace.
- The old issuer keeps working until the last team moves.
- Clear rollback for each team.
Parallel servers: cost
- More objects to manage during the transition.
- Policies and scopes must be copied and kept in sync.
- You must remember to retire the old one.
How SAML Apps Notice the Change
In SAML, the identity provider publishes a metadata document. It lists the provider’s name, its sign-in address, and the certificate used to sign assertions. The app is given this information once, often by uploading the file or pasting the values. If the app is set up with the old values, it keeps working for as long as the old address still serves requests. But if you ever download fresh metadata after the change, you will see the new hostname inside it. Mixed setups, with some apps on old values and some on new, are normal during migration. Keep a simple table of which app is on which.
Some SAML apps are strict about the issuer name. They compare the name inside each assertion with the name they were set up with. If the name changes, they reject the assertion. This is the SAML twin of the OIDC issuer check. For such apps, test the new values in a staging copy before you switch the production one.
A passport officer checks three things: is the stamp real, does the passport name the right country, and has it expired? The issuer check is the “right country” test. If the country renames itself, officers who still look for the old name will turn travelers away, even though the stamp is perfectly genuine. Everyone must learn the new name before the old one stops being printed.
Ask every API team a simple question: “Is your issuer value typed into a config file, read from the discovery document, or hard-coded in the source?” The answer tells you how hard their migration will be. Reading it from the discovery document is the easiest path, because the app learns the change by itself.
Production example: an API gateway that validates for many services
A large platform company puts one API gateway in front of dozens of internal services. The gateway checks every token’s signature, issuer, and audience before passing the request on. Because the check lives in one place, the identity team only has to update one trusted issuer list when moving to a custom domain, instead of coordinating with dozens of service teams. This is a strong argument for centralizing token validation.
9The Sibling Feature: Custom Email Domains
Sign-in pages are only half of what users see from Okta. The other half is email. A custom URL domain does not change who the emails come from. For that, Okta has a separate feature.
What Emails Does Okta Send?
Okta sends many kinds of messages: welcome emails, password reset links, account unlock messages, and multi-factor codes. By default, these come from an Okta sender address. Users often do not recognize this sender, and some mail systems treat it with suspicion.
What a Custom Email Domain Does
A custom email domain lets Okta send these messages from a sender on your own domain, for example no-reply@northwind.com. To make this safe, Okta asks you to publish a small set of DNS records. These records prove that Okta is allowed to send on your behalf. Without them, receiving mail systems could mark the messages as fake.
SPF
Sender Policy Framework. A DNS list of which servers may send mail for your name. Think of it as the guest list at the door.
DKIM
DomainKeys Identified Mail. A digital signature attached to each message. The receiver checks it against a key in your DNS. Think of it as a wax seal on a letter.
DMARC
A policy that tells receivers what to do when SPF or DKIM checks fail. It is set by you, in your own DNS, and it is worth setting up even if you never use Okta.
Custom SMTP server
Instead of Okta sending the messages, you can have Okta hand them to your own mail server. This gives you full control but also full responsibility for delivery.
Why the Two Features Belong Together
Think about a password reset. The user gets an email that looks like it is from your company. They click the link. The link opens a page. If the email sender is on your domain and the page is on your domain, the user sees one consistent story. If either is on an unfamiliar domain, the user must decide whether to trust it. This is the same trust problem that custom domains solve for the sign-in page, now applied to email.
Changing the email sender can affect deliverability. Roll it out gradually, watch bounce and spam-folder rates, and keep DMARC in a monitoring mode first before moving to strict enforcement.
10Brands and Multiple Domains
Many companies are not one company in the eyes of their users. They have staff, partners, and customers, sometimes under several product names. Okta’s brands let one org wear several faces. Custom domains decide which face appears at which address.
What a Brand Controls
A brand is a package of visual and message settings. Inside it you will find the logo and favicon, the color theme, the layout and wording of the sign-in page, the error pages, and the email templates. When a user arrives at an address tied to a brand, the pages they see come from that brand.
Logo, colors, background
The easy visual layer. It changes the feel of the page without touching how authentication works.
Sign-in and error pages
With a custom domain you can go further than colors and edit the page HTML itself, for example to add a short help message or a company link.
Email templates
Welcome, reset, and unlock emails can be reworded and restyled per brand, so a partner never receives a message written for staff.
Custom domain and email domain
Each brand can be linked to its own hostname and, where available, its own email sender domain.
How Okta Decides Which Brand to Show
There are two common ways the brand is chosen. The first is by address: the hostname the user typed or was sent to points at a brand. The second is by app: you can tell Okta that a given app belongs to a given brand, so anyone signing in to that app sees that brand, no matter how they arrived. Which options you have depends on your Okta features and plan, so confirm in the current documentation before designing around it. The idea behind both is the same: the user sees a page that matches the product they came for.
A Simple Three-Brand Layout
flowchart TD
ORG["One Northwind Okta Org"]
ORG --> B1["Brand: Employees"]
ORG --> B2["Brand: Partners"]
ORG --> B3["Brand: Customers"]
B1 --> D1["login.northwind.com"]
B2 --> D2["partners.northwind.com"]
B3 --> D3["account.northwind-shop.com"]
D1 --> A1["Internal apps"]
D2 --> A2["Partner portal"]
D3 --> A3["Shopping site"]
The Cost of Each Extra Domain
Each custom domain is a small project of its own. It needs its own DNS records, its own certificate, its own owner, and its own monitoring. Teams sometimes create a new hostname for every small idea and then struggle to keep track. A good rule of thumb is to add a hostname only when there is a clear audience difference, a legal reason, or a brand difference that users will notice.
| Reason to add another hostname | Worth it? | Why |
|---|---|---|
| A separate product brand with its own customers | Usually yes | Users expect to see the brand name they know. |
| Partners who must not see employee branding | Usually yes | Keeps messages and pages clean for each audience. |
| A regional name for local trust | Sometimes | Good if local rules or customer habits require it. |
| One per team or per project | Rarely | Adds ownership and monitoring work without user benefit. |
| A test hostname for experiments | Better in a test org | Keeps production certificates and DNS tidy. |
Cookies Across Brands
Browsers keep cookies separate for each hostname family. A user who signs in at the employee address will not automatically be signed in at the customer address if the two belong to different main names. That is usually what you want, because it keeps audiences apart. But if one person has both roles, for example an employee who also shops as a customer, they will sign in twice. Plan the experience so this does not surprise them.
Limits on the number of brands and custom domains depend on your Okta plan and may change over time. Check the current limits before promising a design to the business.
Production example: a media group with several consumer products
A media company runs a news site, a streaming service, and a magazine subscription. Each has a different audience and a different look. By using separate brands under one identity layer, each product shows its own logo and address at sign-in, while the company keeps one central place for security policy and user records. This is the same pattern large consumer groups use when they want separate fronts but shared plumbing.
11Performance, Scalability and High Availability
When a sign-in page is slow or down, nobody can work. This chapter explains what a custom domain does and does not change about speed, load, and uptime, and where the weak links really are.
Who Carries the Load
Once traffic reaches Okta’s front door, the work of terminating encryption, finding your org, and running authentication is done on Okta’s side. You do not size servers, add load balancers, or manage failover for it. Okta runs the service across multiple data centers and publishes an availability commitment for its services. Check your contract for the exact number that applies to you. Your job is to make sure nothing on your side of the line becomes the weak link.
Your Side of the Line
The custom domain adds exactly two things that you own: the DNS records and, in one mode, the certificate. These are small, but they sit in front of everything. If either is wrong, nobody gets in, no matter how healthy Okta is. A good way to think about it: Okta is a very strong building, and your DNS record is the road leading to its front door. A strong building does not help if the road is closed.
DNS Performance and Reliability
Every first visit starts with a DNS lookup. Good DNS answers quickly and rarely fails. A few habits help.
- Choose a strong DNS provider. Look for a provider that runs many servers around the world and answers from the one nearest to the user.
- Pick a sensible TTL. A TTL of a few minutes lets you fix mistakes fast but causes more lookups and less protection if DNS has a short outage. A TTL of an hour or more reduces lookups and lets resolvers keep serving the last known answer through short outages, but slows down any fix. Many teams settle between five minutes and an hour and lower it only before planned changes.
- Consider secondary DNS. Some organizations keep a second provider in sync, so that the failure of one provider does not take down their names.
- Protect against accidents. Use change review and zone backups so a bad edit can be undone in minutes.
Why a Proxy in Front Is Usually a Bad Idea
It is tempting to place your own web firewall or content delivery network in front of the custom hostname, so that you can add your own filters. In general this is not recommended for Okta custom domains. Okta uses the visitor’s network address for features such as network zones and risk checks. A proxy in the middle hides the real visitor and can make these features work badly. Proxies can also interfere with how Okta manages the certificate and the CNAME. If you need extra protection, use the controls Okta already offers, such as network zones, behavior rules, and rate limits, and talk with Okta before introducing a proxy.
Rate Limits Still Apply
Okta limits how many requests an org may make in a short time, to protect itself and other customers. These limits belong to your org and are not removed by a custom domain. Sending traffic through a different hostname does not give you a bigger allowance. If you expect a big burst, such as a sale event or a company-wide login at 9 a.m., review the published limits for the endpoints you use and plan for them. Spread token refreshes, cache user information where it is safe, and avoid polling.
flowchart LR
U["Many users"] --> DNS["DNS lookup, cached by TTL"]
DNS --> EDGE["Okta edge"]
EDGE --> RL{"Within org rate limits?"}
RL -->|"Yes"| AUTH["Authentication and tokens"]
RL -->|"No"| BACK["Slow down and retry later"]
AUTH --> APPS["Applications"]
Handling Failure Gracefully
Even with careful design, parts of the path can fail. It helps to think in terms of what the user sees and what you can do.
| What fails | What users see | First response |
|---|---|---|
| DNS provider outage | Site cannot be found | Switch to secondary DNS if you have one, or wait for the provider and keep users informed. |
| Wrong CNAME edit | Site cannot be found, or wrong site | Roll back the record from the zone history. |
| Expired certificate | Browser security warning | Renew or upload at once. Do not tell users to click through. |
| Okta service incident | Slow or failing sign-in | Check Okta’s status page and follow your continuity plan. |
| Hit rate limits | Some requests refused | Reduce request bursts and retry with backoff. |
An airport can have world-class runways and still fail to move passengers if the road to the airport is closed or the ticket scanner at the gate breaks. Okta is the airport. Your DNS record is the road, and your certificate is the scanner at the gate. Keep both in working order, and keep a plan for the day one of them is not.
Production example: a retailer on a peak shopping day
A retailer expects many times its normal sign-in traffic on a major sale day. The team checks that DNS TTLs are reasonable, that the certificate has months left, that app token refresh is spread out instead of firing all at once, and that the synthetic sign-in check is running every minute. On the day, the traffic spike is handled without drama, because the plan focused on the parts the team controls.
12Advantages, Disadvantages and Trade-offs
Every design choice has a price. A custom domain gives you real benefits, but it also gives you something new to look after. A good architect weighs both sides before saying yes.
Advantages
- Brand trust. Users see your name, not a shared name.
- Simpler security rule. One hostname to learn and one to protect.
- Better browser behavior. First-party cookies make silent sign-in more reliable.
- Deeper customization. Full control over page HTML and error pages becomes available.
- Future flexibility. Because apps point at your name, you have more freedom later in how the identity layer is arranged.
- Consistency. The same style of address across sign-in pages and emails.
Disadvantages
- New dependency on your DNS. A wrong change in your zone can break sign-in.
- Certificate duty. Even in the managed mode, you must keep DNS records in place. In the other mode, you must renew.
- Migration work. Every app that uses the old address must be reviewed.
- Token issuer changes. Validators across many services may need updates.
- Ownership questions. Someone must own the hostname for years, even after staff change.
- More places to test. Browsers, mobile apps, and device features all need checks.
The Trade-off Table
| Question | Default Okta address | Custom domain |
|---|---|---|
| Time to start | Instant | About an hour of setup, plus DNS wait time |
| Brand visible to users | Partly Okta’s | Fully yours |
| Full page HTML customization | Not available | Available |
| Cookie treatment by browsers | Often third-party | First-party when on the same main name |
| Who looks after the certificate | Okta | Okta or you, by choice |
| Risk if DNS is broken | None for the default address | Custom hostname stops working |
| Long-term ownership burden | Low | Moderate |
When to Say No (For Now)
A custom domain is not always the right first step. If you are running a short proof of concept, if you do not control any DNS zone yet, or if your team is too small to own another piece of infrastructure, the default address is a perfectly good choice. Start simple. Move to a custom domain when brand, security training, or browser behavior make it worth it.
Owning a car is better than relying on taxis when you travel every day. You get freedom and comfort. But you must now pay for insurance, remember service dates, and find parking. If you only travel once a month, a taxi is cheaper and simpler. A custom domain is the car: great value when you use it a lot, extra homework when you do not.
13Security
Identity is the front door of every system you run. A custom domain moves part of that door under your control, so security thinking has to move with it.
Benefits You Gain
Easier phishing defense. Phishing is when an attacker makes a fake page that looks like a real one to steal passwords. Attackers love shared platforms, because they can make a look-alike address within the same family of names. When your real sign-in lives at one hostname that you own, security training becomes one sentence. Users learn the single address, and anything else is wrong.
Stronger browser guarantees. A custom hostname is served over encrypted connections with a certificate for your name. Modern browsers warn loudly when something is off, which gives users a clear signal when they land somewhere unexpected.
Clean separation. Cookies and storage on your hostname are separate from Okta’s other customers, because browsers isolate data by name.
New Risks You Take On
DNS takeover. If an attacker can change your DNS records, they can point your sign-in hostname to a server they control and collect passwords. Treat the DNS zone for your sign-in name as critical infrastructure. Limit who can edit it, require approval for changes, and turn on multi-factor sign-in for your DNS provider’s console.
Dangling records. If you delete the Okta custom domain but leave the CNAME in place, the alias now points at a target that might be claimable by someone else in the future. Always remove DNS records as part of retiring a domain. Clean up in the right order: stop using the name, remove it from Okta, then remove the DNS record.
Certificate mishandling. In bring-your-own mode, the private key is the crown jewel. Anyone holding it can impersonate your hostname. Generate it in a safe place, upload it once, and do not store copies on shared drives or in email.
Expiry outages. An expired certificate is a security incident of its own kind. Browsers will block users, and teams under pressure may tell users to “just click through” the warning. That habit is far more dangerous than the outage itself.
Never train users to click past a certificate warning on your sign-in page, even once, even in an emergency. The habit is exactly what attackers hope for.
Practical Security Controls
Lock down the zone
Use role-based access, change approvals, and alerts for any edit to the sign-in hostname’s records.
Use DNSSEC where possible
DNSSEC adds signatures to DNS answers so resolvers can detect tampering. It is not required by Okta, but it helps protect the lookup step.
Prefer automated certificates
Fewer human steps means fewer chances to leak a key or forget a date.
Strong authentication policies
The custom domain does not replace multi-factor rules. Keep strong sign-in policies, phishing-resistant factors, and device checks in place.
Enforce SPF, DKIM, DMARC
If you use a custom email domain, authenticated email protects users from forged messages that claim to come from you.
Name an owner
Write down which team owns the hostname, the DNS records, and the certificate. Include a backup owner.
Production example: look-alike domains at a bank
Financial companies commonly register many look-alike names to stop attackers from using them, and they teach customers to use exactly one sign-in address. A custom domain makes this teaching practical for companies that use Okta, because the one address matches the brand customers already know.
14Monitoring, Logging and Metrics
A custom domain is quiet when it works and loud when it fails. Good monitoring makes sure you hear about trouble before your users do.
Three Layers to Watch
Think of your sign-in path as three layers. Each can fail on its own, and each needs its own alarm.
DNS layer
Is the hostname resolving? Does the CNAME still point at the Okta target? Run a check from several places in the world every few minutes. Alert if the answer changes unexpectedly, because this is also your early warning for tampering.
Certificate layer
Check the real certificate served to the public, not the file you think you uploaded. Alert when fewer than thirty days remain, then again at fourteen and at seven. Even with automatic renewal, this external check catches the day when automation quietly stops working.
Sign-in layer
Use a synthetic check, which is a robot user that opens the sign-in page on a schedule and confirms the page loads and shows the right content. Add a deeper check that completes a real test sign-in with a dedicated test account, if your policies allow it.
Using the Okta System Log
The System Log is Okta’s record of what happens in your org: sign-ins, policy decisions, and administrator changes. Changes to domains and certificates are recorded here, so you can answer who changed what and when. For long-term storage and alerting, many teams stream the log to an outside tool. Okta supports log streaming to services such as AWS EventBridge and Splunk Cloud, which lets you build alerts and keep records for as long as your rules require.
Useful Metrics
| Metric | What it tells you | Healthy sign |
|---|---|---|
| Days until certificate expiry | Whether renewal is on track | Never falls below the renewal window |
| DNS resolution success rate | Whether users can find the hostname | Close to 100 percent from every region |
| Sign-in page load time | Perceived speed for users | Stable, with no sudden jumps |
| Sign-in failure rate | Policy or app problems | Flat, apart from known incidents |
| Share of traffic on old address | Progress of migration | Falling toward zero |
| Silent sign-in failures in browsers | Cookie and frame issues | Lower after moving to a first-party name |
Put the certificate expiry date, the DNS owner, and the Okta admin contact in one shared runbook page. When the alert fires at 3 a.m., nobody should need to search for who to call.
A Short Incident Story
Imagine a team that moved to a bring-your-own certificate. The person who uploaded it left the company, and the renewal reminder went to their old mailbox. On the expiry day, every sign-in showed a browser warning. The fix took ten minutes once someone found the right file, but finding it took three hours. The lesson is simple: reminders must go to a shared team address, and an outside check should watch the real certificate so the alarm does not depend on one person’s inbox.
15Design Patterns and Anti-patterns
A pattern is a solution that many teams have found useful. An anti-pattern is a tempting shortcut that tends to hurt later. Here are the ones that matter most for custom domains.
Patterns That Work
One stable sign-in hostname
Pick a short, neutral name like login or sso and keep it for years. Apps change, brands change, but a neutral hostname survives both.
Same main name as your apps
Where possible, put the sign-in hostname under the same main name as your web apps to get first-party cookie behavior.
Brand per audience
Use Okta brands to give workforce, partners, and customers different looks and, where your plan allows, different hostnames, while keeping one org underneath.
Infrastructure as code
Describe the domain, verification, and DNS records in a tool such as Terraform, which has Okta support. Changes then go through review and leave a history.
Staged cutover
Enable the custom domain first for a small pilot group, then widen it step by step, while the old address keeps working as a safety net.
External canary
Run a robot user from outside your network that checks DNS, certificate, and sign-in page, so you learn about failures the way a real user would.
Anti-patterns to Avoid
What it looks like
A team uses the bring-your-own certificate mode and sets a calendar reminder on one person’s personal calendar.
Why it hurts
People change jobs, calendars get cleaned up, and the certificate expires without anyone noticing until users complain.
Better approach
Use the Okta-managed certificate where policy allows. Otherwise send reminders to a shared mailbox and add an outside certificate monitor.
What it looks like
A hostname is named after a project, such as the name of a program the company ran two years ago.
Why it hurts
When the project ends, the name becomes confusing, and changing it means repeating the whole migration.
Better approach
Use a plain, role-based name that describes what the address does, not what the company is currently busy with.
What it looks like
The DNS records for the sign-in hostname live in a zone that dozens of people can edit, with no review.
Why it hurts
One careless edit, or one stolen account, can send every user’s password to the wrong place.
Better approach
Restrict edits, require review, and alert on every change to these records.
What it looks like
The team changes the token issuer to the custom address on a Friday afternoon, without telling the owners of the APIs that check tokens.
Why it hurts
Every API that expects the old issuer starts rejecting valid tokens. Users see sign-in succeed and then every page fail.
Better approach
List every token validator first, update them to accept the new issuer, then switch the issuer in a planned window with a rollback plan.
16Best Practices and Common Mistakes
These are the habits that separate smooth custom domain projects from stressful ones. Most of them are simple, and almost all of them are about planning and ownership, not about clever technology.
Best Practices
- Pick the name carefully. Choose a short, role-based subdomain that you can keep for the next five years. Say it out loud to a colleague on the phone. If it takes spelling out, choose a simpler one.
- Prefer Okta-managed certificates. Unless a policy forces you to use your own, automatic renewal removes the most common cause of outages.
- Lower the DNS TTL before the change. A short TTL a day ahead lets you fix a wrong record quickly. Raise it again once things are stable.
- Check your CAA records first. Make sure the certificate authority used by Okta is allowed to issue for your name.
- Test in a safe org first. If you have a preview or test org, rehearse the full process there, including the DNS steps, before touching production.
- Build a migration inventory. List every SAML app, OIDC client, API validator, mobile app, bookmark, and script that mentions the old address.
- Keep a break-glass path. Make sure at least two administrators can still get into the Admin Console if your hostname or DNS has trouble.
- Document ownership. Write down who owns the domain registration, the DNS zone, the Okta settings, and the monitoring. Include backups for each.
- Announce the change. Tell users and help desk staff what the new address is, when it starts, and what they should do if they see the old one.
- Review after thirty days. Check the metrics, close out leftover old-address usage, and update your runbook with anything you learned.
Common Mistakes
Deleting the CNAME “to tidy up”
With an Okta-managed certificate, this stops renewals. The break shows up weeks later, which makes it hard to trace.
Using the main name instead of a subdomain
An alias on the bare main name conflicts with other records that the main name must hold, such as mail records. Use a subdomain.
Forgetting the chain in an upload
A certificate without its intermediate certificates works on some devices and fails on others, which makes bug reports look random.
Uploading a key with a passphrase
Okta expects the private key in a form it can use directly. A key locked with a passphrase may be rejected. Check the current requirements before you upload.
Changing the issuer without warning
Every token validator breaks at once. Always inventory validators first.
Skipping mobile and device tests
Browser testing is not enough. Test Okta Verify, mobile apps, and any desktop clients with the new address before the wide launch.
Leaving the old address as the official one
Help desk scripts and wiki pages still tell people to use the old address, so your security rule never becomes real.
Assuming DNS changes are instant
Impatient teams re-do steps that were already correct, which creates extra records and extra confusion. Wait for the TTL.
Before you click verify, look up your own TXT record from a public DNS checking tool. If the public lookup shows the right value, Okta will see it too. This saves many failed attempts.
17A Safe Rollout Plan
A custom domain is easy to switch on and slow to roll out well. This plan moves from preparation to full adoption in small, reversible steps.
Prepare
Confirm domain ownership, pick the hostname, check CAA records, list owners, lower the TTL, and build the inventory of places that use the old address.
Set up and verify
Add the domain in Okta, publish the TXT record, verify, then publish the CNAME. Wait for the certificate to become ready.
Test quietly
Use a small test group and a few test apps. Check desktop browsers, phones, and Okta Verify. Check that error pages and emails look right.
Update apps in waves
Move low-risk apps first, then business-critical ones. For OIDC apps, handle the issuer change as its own planned step. Keep the old address working during this phase.
Announce and train
Tell all users the new address, update bookmarks and help articles, and brief the help desk. State clearly that this is the only address to trust.
Watch and finish
Monitor the share of traffic still on the old address. When it is close to zero, remove leftover references and review the whole project.
flowchart LR
P["Prepare and inventory"] --> S["Set up and verify"]
S --> Q["Quiet pilot"]
Q --> W["App waves"]
W --> N["Announce and train"]
N --> M["Monitor old address use"]
M --> D["Retire old references"]
W -.->|"Problem found"| R["Pause and fix"]
R -.-> W
Moving a shop to a new street is easier if you keep the old shop open for a few weeks. You put up a sign saying “We have moved,” you tell your regular customers, and you only close the old doors when almost nobody walks in. Rolling out a custom domain follows the same gentle path.
18Troubleshooting Guide
When something goes wrong, the fastest path is a calm, ordered check. Almost every custom domain problem comes from one of three places: DNS, the certificate, or the settings in Okta and the apps. This chapter shows how to tell them apart.
The Three-Question Method
Ask these three questions in order. Each answer narrows the search.
Does the name resolve to the right place?
Look up the hostname from more than one network. It should return the Okta target through your alias. If it returns nothing, or something else, the problem is in DNS.
Is the certificate valid for this name?
Open the hostname in a browser and inspect the certificate. Check that the name matches, the dates are valid, and the full chain is present. If a warning appears, the problem is in the certificate.
Does the right page load, and do the apps agree?
If the first two checks pass but sign-in still fails, look at the brand, the policies, the issuer, and the app settings.
flowchart TD
S["Problem reported"] --> Q1{"Does hostname resolve to Okta target?"}
Q1 -->|"No"| F1["Fix DNS: records, TTL, typos"]
Q1 -->|"Yes"| Q2{"Certificate valid and chain complete?"}
Q2 -->|"No"| F2["Fix certificate: renew, upload chain, check CNAME and CAA"]
Q2 -->|"Yes"| Q3{"Sign-in page loads correctly?"}
Q3 -->|"No"| F3["Check domain status and brand in Okta"]
Q3 -->|"Yes"| Q4{"Do apps accept the tokens or assertions?"}
Q4 -->|"No"| F4["Check issuer, audience, metadata and redirect settings"]
Q4 -->|"Yes"| F5["Check policies, network zones and user-specific issues"]
Symptom Table
| Symptom | Likely cause | What to check |
|---|---|---|
| Verification keeps failing | TXT record not visible yet, wrong name, or a typo in the value | Look up the TXT record from public DNS. Compare the name and value character by character. Wait for TTL. |
| Certificate stays pending | CNAME missing, wrong target, or CAA blocks the authority | Check the CNAME target against Okta’s screen. Review CAA records. |
| Browser shows a security warning | Expired certificate, wrong name, or missing intermediate certificates | Inspect the certificate details. Re-upload with the full chain if you manage it yourself. |
| Works on laptops, fails on some phones | Incomplete certificate chain | Some devices fetch missing intermediates, others do not. Include the full chain. |
| Works for some users, not others | DNS cache differences | Wait for TTL to pass. Ask affected users to try another network to confirm. |
| Users sign in, then land back on sign-in | Cookie or session mismatch between old and new hostnames | Check that the app uses one hostname consistently. Clear cookies and retest. |
| Every API call fails after sign-in works | Issuer changed but validators were not updated | Compare the issuer in a sample token with the validator’s setting. |
| SAML app rejects assertions | App holds old issuer or sign-in address | Update the app with fresh metadata from Okta and test again. |
| Redirect error after sign-in | Redirect address in the app does not match what Okta allows | Compare the app’s actual return address with the list in Okta, including trailing parts. |
| Reset emails land in spam | Email authentication records missing or wrong | Check SPF, DKIM, and DMARC for the sender domain. |
| Okta Verify will not enroll | Device flow not tested with the new address | Test on a real device and review current Okta guidance for device features. |
| Fine for weeks, then suddenly broken | Managed certificate could not renew because CNAME was removed or changed | Restore the CNAME and check the domain status page in Okta. |
Things to Collect Before Asking for Help
If you need to open a support case, a good report saves hours. Gather these items first: the exact hostname, the time of the first failure, a screenshot of the browser warning if there is one, the DNS lookup results from two networks, the domain status shown in Okta, and any recent changes made to DNS or Okta settings. The most common root cause of a sudden failure is a change that someone forgot to mention, so ask around early.
Keep a short change log for the sign-in hostname: every DNS edit, every certificate action, and every Okta domain setting change, each with a date and a name. When trouble starts, this log is often the fastest way to find the cause.
While you are troubleshooting, do not delete and re-create the custom domain unless you have to. Doing so can leave stale DNS records behind and may cause new verification problems. Fix the specific issue first.
19Governance and Operating Model
Technology is the easy half of a custom domain. The harder half is keeping it healthy for years: who owns it, who can change it, and what happens when people move on. This chapter covers the people and process side.
Who Owns What
A custom domain sits across several teams. If no one is clearly in charge of a piece, that piece is the one that will break. Write down an owner and a backup for each item below.
| Item | Typical owner | Why it matters |
|---|---|---|
| Main domain registration | IT or legal operations | If the registration lapses, every name under it stops working. |
| DNS zone and records | Network or platform team | The road to Okta. A bad edit blocks all sign-ins. |
| Okta domain settings | Identity team | Controls verification, certificate mode, and brand links. |
| Certificate lifecycle | Identity or security team | Renewals, uploads, and expiry alerts. |
| Token validators and apps | Application owners | They must accept the new issuer and addresses. |
| Monitoring and alerts | Site reliability or operations | Early warning before users notice. |
| User communication | Help desk and internal communications | Keeps the “one trusted address” rule alive. |
The Hidden Risk: Domain Registration Expiry
Most teams worry about certificates, but a quieter risk sits one level up. The main name, such as the one your company has used for years, is rented from a registrar for a set period. If that rental lapses, your whole name can stop working, and someone else may even buy it. Turn on automatic renewal, put the payment on a company account rather than a personal card, send reminders to a shared mailbox, and consider asking the registrar for a lock that prevents transfers and quiet changes.
Your sign-in hostname is a shop on a street. The certificate is the shop’s license, and the DNS record is the street sign pointing to it. The registration of the main name is the land lease under the whole street. You can keep the license and the sign perfect, but if the lease runs out, the street disappears.
Change Management
Changes to the sign-in hostname are rare, but they carry high risk. Treat them the way you would treat a change to a payment system.
- Review before change. A second person checks every edit to the DNS records and Okta domain settings.
- Change windows. Prefer calm hours with staff available, and avoid Fridays and busy business days.
- Rollback plan. Before any change, write down how to undo it and how long that takes.
- Post-change check. After each change, run the three-question test from Chapter 18 and confirm monitoring is still green.
- Records. Save a short note of what changed, who approved it, and when.
Compliance and Audit
Auditors who review a company for standards such as SOC 2 or ISO 27001 often ask about identity systems. A custom domain adds a few things they may want to see: a list of who can edit DNS for the sign-in hostname, evidence of regular certificate checks, proof that changes are reviewed, and a documented process for retiring old names. The practices in this guide, such as ownership tables, change logs, and outside monitoring, double as audit evidence. Collecting them as you go is far easier than gathering them in a hurry later.
Business Continuity
Plan for the day when the normal path is not available. A few simple steps go a long way.
Break-glass access
Keep at least two administrator accounts that can reach the Okta Admin Console without relying on your custom hostname, and protect them with strong factors and tight storage of credentials.
Documented fallback
Decide in advance whether, and for how long, users may use the original Okta address in an emergency, and who can approve that exception.
Communication plan
Prepare a short message template for staff and customers, and list who sends it and through which channel that does not depend on sign-in.
Practice
Run a short tabletop exercise once a year. Pretend the certificate has expired or the DNS record has been changed, and walk through who does what.
Retiring a Custom Domain
Eventually a hostname may be replaced, for example after a rebrand. Retire it in a safe order. First, move users and apps to the new hostname and watch the old one’s traffic fall to near zero. Second, remove the domain from Okta so it no longer serves your org. Third, delete the DNS records that pointed to Okta. Doing the third step last, never first, avoids a gap, and doing it at all avoids leaving a dangling alias that someone else might misuse. Finally, update the ownership table and the change log.
Production example: a regulated company with annual reviews
A company in a regulated industry adds the sign-in hostname to its yearly access review. Each year, the team confirms who can edit DNS, checks that certificates and registrations auto-renew, runs the tabletop exercise, and files the results. The review takes about an hour, and it has twice caught a former employee who still had edit rights.
20Real-World and Industry Examples
Here are four situations where a custom domain pays off. The companies are described by type, since each real project is different and the details are private.
Workforce sign-in for a large employer
A company with tens of thousands of staff wants one rule for security training: “Only sign in at our company’s own sign-in address.” After moving to a custom domain, the awareness team replaces long slides with one short instruction, and the help desk can spot fake pages quickly because the correct address is so simple.
Customer sign-in for a consumer brand
A streaming or retail brand with millions of users needs customers to feel they never left the brand. With a custom domain on a brand-specific page, the customer sees the logo, the colors, and the address they know. The same approach is common among big consumer companies that own their own sign-in hostnames.
Partner portals with several brands
A group of companies under one parent uses one org but several brands. Each brand has its own address, logo, and email sender, so partners of each brand see only their own world, while the central identity team manages everything in one place.
Single-page apps that rely on silent sign-in
A product team builds a browser app that checks the user’s session quietly in a hidden frame. On the default address, Safari blocked the session cookie as third-party, and users were asked to sign in again and again. After moving to a sign-in hostname under the same main name as the app, the quiet check worked, and re-sign-in prompts dropped sharply.
A Worked Example in Numbers
Let us walk through a small planning exercise. Suppose Northwind has 40 SAML apps, 25 OIDC apps, and 12 APIs that validate tokens. The team plans three waves. In wave one, they move 10 low-risk SAML apps. In wave two, they move the remaining 30 SAML apps and 15 OIDC apps. In wave three, they move the last 10 OIDC apps and update all 12 APIs for the new issuer. The old address stays alive for the whole time. After the last wave, the share of sign-ins still using the old address falls to under one percent, and the team retires the old references. The total hands-on time is spread across several weeks, but no user ever sees an outage.
21Frequently Asked Questions
Short answers to the questions that come up most often.
22Summary and Key Takeaways
A custom domain turns Okta’s shared front door into your own front door. The cost is a little more care. The gain is trust, clarity, and better browser behavior.
Key Takeaways
- It is a new front door, not a new house. Your users, apps, and policies stay in the same Okta org. Only the address people see changes.
- Two DNS records do the heavy lifting. The TXT record proves you own the name, and the CNAME record sends traffic to Okta. Keep both in place.
- Choose the certificate mode on purpose. Okta-managed saves work and avoids expiry outages. Bring your own gives control but needs a reliable renewal process, which matters more as certificate lifetimes shrink.
- Plan for the token issuer and app updates. The change reaches SAML apps, OIDC clients, and API validators, so build an inventory and migrate in waves.
- Same-name cookies work better. A sign-in hostname under your own main name makes session cookies first-party, which fixes many silent sign-in problems.
- Protect DNS like it is the front door lock. Limit edits, require review, and alert on changes, because whoever controls the record controls where passwords go.
- Monitor from outside. Watch DNS, the real certificate, and a robot sign-in, and send alerts to a shared team address, not to one person.