Custom domains

A custom domain is a hostname you own, such as login.acme.com, for your directory’s portal and sign-in. Once it’s active, people who open your portal at https://<alias>.sso.ezgh.app are sent there, and emails link to it.

Once you’ve created two DNS records, EZGH SSO issues a certificate for the hostname (Let’s Encrypt, renewed automatically) and serves the directory there. An active custom domain is its own issuer, and the OpenID Connect and SAML endpoints at https://<alias>.sso.ezgh.app keep working alongside it.

You need sso.customDomains.create (in SsoFullAccess). A directory has one custom domain: to use another hostname, remove the current one first (adding a second is 409 too_many_custom_domains).

Add a custom domain

ezgh sso custom-domains create login.acme.com
ezgh sso custom-domains get login.acme.com

A hostname is lowercase ASCII (an internationalized name in its xn-- form), and EZGH’s own domains are refused. The domain’s records are the two records to create:

The CNAME always names your directory’s current alias. An apex domain (acme.com) can’t have a CNAME, so it can’t be a custom domain: use a subdomain. If your domain has CAA records, they must allow letsencrypt.org, or the certificate can’t be issued.

Status

EZGH SSO checks the records as soon as you add the domain, then every 15 minutes for a week. VerifyCustomDomain (ezgh sso custom-domains verify login.acme.com) asks for a check within seconds, and restarts the week. Each record shows whether the last check found it; checkError says why the last check didn’t verify the domain, and verifiedAt when both records were found.

• A verified domain is checked again every 6 hours. If either record is missing twice in a row, it goes back to pending. A DNS failure or timeout changes nothing.
• The CNAME may point through a chain to <alias>.sso.ezgh.app. After an alias change, the old alias is accepted during its 30-day redirect.
• A hostname is claimed by one directory at a time. Another directory can add it, but it stays pending, with checkError saying it’s claimed elsewhere, until the first directory removes it or loses its records.
• Status changes are recorded in Trails as UpdateCustomDomainStatus.

The domain’s certificate shows notAfter and, if issuance fails (for example a CAA record that doesn’t allow Let’s Encrypt), error. Fix the cause and EZGH SSO tries again.

Using an active custom domain

• Its own issuer. An active domain’s issuer is https://<hostname>, with its own /.well-known/openid-configuration. Point an OpenID Connect application at the issuer it should use. Codes and tokens only work on the host that issued them, so an application uses one issuer.
• SAML. On a custom domain, a SAML application’s identity provider entity ID and metadata are https://<hostname>/saml/metadata/<applicationId>. Use the metadata from the host the service provider should trust.
• Your portal moves there. Opening the portal, sign-in or account pages, or an activation or reset link, at https://<alias>.sso.ezgh.app redirects to the same page on your custom domain. The OpenID Connect and SAML endpoints there aren’t redirected, so applications set up with that issuer or entity ID keep working, and a sign-in an application starts there finishes there. Removing the custom domain ends the redirect at once.
• Emails. Activation and factor-reset links use your custom domain.
• Passkeys belong to a host. A passkey registered at <alias>.sso.ezgh.app doesn’t work at your custom domain, and the other way round. Someone who enrolled a passkey before you added the custom domain signs in there with another sign-in method, or adds a passkey after an administrator resets their sign-in methods.

Remove a custom domain

DeleteCustomDomain (ezgh sso custom-domains delete login.acme.com) removes it at once. Deleting the directory removes its custom domains too.