1. Docs
  2. Authentication
  3. Set up a custom auth domain

Set up a custom auth domain

Serve Canopy's hosted sign-in pages from your own subdomain: add the domain in the Developer Console, publish its DNS records, verify, and remove it.

Add and verify the domain

In the Developer Console, Access Control → Integrations → Custom Auth Domain holds one domain per Environment. It must be a subdomain such as auth.example.com: an apex domain cannot carry the required CNAME record.

Application
Developer Console
Path
Access ControlIntegrationsCustom Auth Domain
Opens with
  • sso.view Read SSO connections, verified domains, the custom auth domain, and directory sync.
Context
Select an Application and an Environment in the switcher first; the page belongs to that Environment.
Add and verify the domain
Open Custom Auth Domain from the left nav under Access Control → Integrations. With nothing configured the page reads No custom auth domain; click Add domain.In the Add custom auth domain dialog, enter the subdomain and submit. An apex domain is refused inline with an explanation. On success the page shows a summary card with the hostname, a Pending DNS badge, and the records to publish.Publish the records exactly as listed: a TXT record at _canopy-verify.<your host> with the shown value, and, where the deployment provides a target, a CNAME record pointing the host at it. Each value has a copy field.Click Verify. Until the records are visible in DNS the badge stays Pending DNS and an error toast says so; verification never passes on absent records. Once they resolve, the badge changes and hosted sign-in serves from your domain.Click Remove to drop the domain. A success toast confirms it and the page returns to No custom auth domain.
If you don't see this

Each control on this page exists only for someone who may use it. When something described above is missing, one of these is why:

Custom Auth Domain is not under Integrations. Either no Application and Environment is selected yet, or your administrator role does not carry sso.view, which this page shares with the SSO surfaces.There is no Add domain, Verify, or Remove. You hold sso.view but not sso.manage.The dialog refuses the domain. It is an apex domain, or it includes a scheme or a path. Enter a bare subdomain.
How hosted login works →
Environment
API version
v1.0
 On this page Was this page helpful?

Tell us how we can improve this guide.

Canopy