Choosing a Domain Name

This book makes many references to a "domain name". This is the DNS domain name that you intend to use for Kanidm.

This isn't always simple, and this chapter covers the key issues to consider when choosing a domain.

Considerations

Use a domain under your exclusive control

You should always use a domain name that you've registered and directly control its DNS.

While example.com and top-level domains ending in .example appear throughout this book, these are examples only. You should not use this outside of testing.

You'll need a registered domain for a CA (certificate authority) to issue you a TLS certificate which is widely accepted by browsers. This will also prevent those same CAs from issuing a certificate for that domain to someone else.

If you use a domain controlled by someone else (eg: a Dynamic DNS provider, or your cloud provider), they could take over that domain whenever they like. They could also use control of DNS or email to convince a CA to issue a certificate for that domain.

Any party who holds a valid certificate for the domain can steal or issue credentials.

Avoid non-public and reserved domains

Avoid using "made-up" (eg: .lan) or reserved domains (eg: .local), because your clients may leak credentials if they move to another network, aren't connected to a VPN, or if it collides with new TLDs.

Properly-configured TLS can prevent most (but not all) leakage, but defence in depth is best.

This will also ensure your infrastructure is accessible regardless of your users' local network conditions.

Domain authorities

Domain authorities can set their own eligibility policies for registering a top-level domain. They may also allow a third-party to challenge your claim to a top-level domain, subject to a dispute resolution policy. These policies may change over time for commercial or political reasons.

If your domain is on a ccTLD (country TLD), it may be de-registered should that country cease to exist (eg: as for .io).

Top-level domains containing "kanidm"

We ask that you do not use the word kanidm as part of your instance's top-level (or public-suffix-level) domain, eg: contoso-kanidm.example.

Use something like auth, idm, login or sso instead – they're shorter, too!

We're OK with you using kanidm in a subdomain to point to your Kanidm instance, eg: kanidm.example.com.

We've worked hard to build this project, and using its name in conjunction with an organisation not associated with the project dilutes the name's brand value.

Subdomains and Cross-Origin policy

Browsers allow a server on a subdomain to use intra-domain resources, and access and set credentials and cookies from all of its parents until a public suffix. This can allow a malicious or compromised service to attack other services which share a parent domain.

Public suffix rules are mostly predictable, but has some exceptional cases. For example:

• host.a.example.com can access and set cookies for:

  • host.a.example.com (itself)
  • a.example.com
  • example.com

  But not the public suffix .com.

• host.a.example.qld.gov.au can access and set cookies for:

  • host.a.example.qld.gov.au (itself)
  • a.example.qld.gov.au
  • example.qld.gov.au

  But not any public suffix:

  • qld.gov.au (Queensland state government)
  • gov.au (Australian federal government)
  • .au (Australia)

• host.a.example.nsw.gov.au can access and set cookies for:

  • host.a.example.nsw.gov.au (itself)
  • a.example.nsw.gov.au
  • example.nsw.gov.au
  • nsw.gov.au (NSW state government has opted out)

  But not any public suffix:

  • gov.au (Australian federal government)
  • .au (Australia)

This can be an issue if Kanidm shares a domain with:

• applications which serve raw, user-supplied data in APIs (eg: blob/file storage and Matrix homeservers)
• third-party servers outside of your organisation's control (eg: SaaS apps)
• anything which can be deployed to with minimal oversight (eg: a web host that allows uploading content via unencrypted FTP)
• DNS entries that resolve to arbitrary IP addresses (eg: 192-0-2-1.ipv4.example.com to 192.0.2.1, and 192.0.2.1 is not under the authority of example.com)

In most cases, hosting Kanidm on a subdomain of a separate top-level (or existing public-suffix level) domain (eg: idm.contoso-auth.example) is sufficient to isolate your Kanidm deployment's Origin from other applications and services.

Kanidm requires its own hostname

Kanidm must be the only thing running on a hostname, served from /, with all its paths served as-is.

It cannot:

• be run from a subdirectory (eg: https://example.com/kanidm/)
• have other services accessible on the hostname in subdirectories (eg: https://idm.example.com/wiki/)
• have other services accessible over HTTP or HTTPS at the same hostname on a different port (eg: https://idm.example.com:8080/)

These introduce similar security risks to the subdomain issues described above.

One reasonable exception is to serve ACME HTTP-01 challenges (for Let's Encrypt) at http://${hostname}/.well-known/acme-challenge/. You'll need a separate HTTP server to respond to these challenges, and ensure that only authorised processes can request a certificate for Kanidm's hostname.

Avoid wildcard and widely-scoped certificates

CAs can issue wildcard TLS certificates, which apply to all subdomains in the same domain (eg: *.example.com).

This is used by some organisations to avoid leaking information about what services exist on a domain in certificate transparency logs. However, this information will exposed anyway whenever a client makes a DNS query.

If a service is issued a wildcard TLS certificate which also covers a Kanidm installation on the same domain, any DNS hijacking could let that service impersonate Kanidm to those clients, and steal credentials.

While DNS-over-HTTPS generally prevents local hijacking, it's possible for a network to disable it when automatically enabled, or just block it entirely.

Sharing a single certificate between many services increases the risk that the private key may be exposed, and broadens the impact scope.

Separate production and testing environments

If running more than one instance of Kanidm, ensure that no two deployments share the same subdomain. This prevents credential and cookie transfers between the two environments. For example:

• Production: idm.example.com
• Testing: idm-test.example.com

If you instead had an instance of Kanidm at idm.example.com for production and another at test.idm.example.com for testing, then the test instance could access the credentials and cookies of the production environment.

This also prevents credentials intended for the test environment from being used in production (where there may be stricter controls).

Regional deployments

You could have multiple instances of Kanidm configured with replication, with a single domain name and origin (eg: idm.example.com).

You could then make regional instances accessible from different host names (eg: au.idm.example.com and nz.idm.example.com).

This allows credentials and cookies to be freely transferred between hosts that are part of a single environment.

Recommendations

For maximum security, your Kanidm domain name should be a subdomain of a top-level domain (or domain under a public suffix) that has no other services assigned it, eg:

• Origin: https://idm.example-auth.example
• Domain name: idm.example-auth.example

If you have strict security controls for all apps on your top-level domain, you could run Kanidm on a subdomain of your main domain, eg:

• Origin: https://idm.example.com
• Domain name: idm.example.com

But running Kanidm on a separate top-level domain makes it much easier to restrict changes that could affect your IDM infrastructure.

Multi-environment and regional deployments

If we were to run regional instances, and have a separate testing environment, the following domain and hostnames could be used:

Production environment

• Origin: https://idm.example.com
• Domain name: idm.example.com
• Host names: australia.idm.example.com, newzealand.idm.example.com

This allows us to have named regional instances such as https://australia.idm.example.com which still works with WebAuthn and cookies which are transferable between instances.

It is critical no other hosts are registered under idm.example.com.

Testing environment

• Origin: https://idm-test.example.com
• Domain name: idm-test.example.com
• Host names: australia.idm-test.example.com, newzealand.idm-test.example.com

This puts the testing instance under a separate subdomain of the top-level domain to production (idm.example.com), so cookies and WebAuthn tokens can not be transferred between them.

This provides proper isolation between the instances.

Bad domain names

Domains you should avoid:

idm.local

The .local top-level domain is reserved for multicast DNS.

If a client visits another network, it may try to contact idm.local believing it is on its usual network. If TLS certificate verification were disabled (or not configured correctly), this would leak credentials.

example.com

Using the top-level domain directly allows any subdomain of that domain to access credentials and cookies intended for Kanidm.

idm.example.nsw.gov.au

nsw.gov.au has opted out of being a public suffix, so all domains under that suffix (except schools.nsw.gov.au) share origin and cookies.

idm.examplekanidm.example

Kanidm is the brand for this project.

Multi-instance with overlap

• Production:

  • Origin: https://idm.example.com
  • Domain name: idm.example.com

• Testing:

  • Origin: https://test.idm.example.com
  • Domain name: test.idm.example.com

While the production instance has a valid and well defined subdomain that doesn't conflict, because the testing instance is a subdomain of production, it allows production cookies to leak to the testing environment.

Testing environments may have weaker security controls in some cases which can then allow compromise of services using the production instance.