Skip to content

Declare the tenant's email domains

Claim the email domains your organization owns, so that sign-in through your identity provider can be routed and admitted for addresses of those domains, and remove a claim you no longer need.

Who can do it

A tenant administrator or a tenant access administrator, or a platform super administrator working inside your tenant.

  • The Verified email domains section is shown to someone who can read your tenant's identity providers (admin.tenant.idp.read).
  • Claiming and removing need the permission to configure identity federation (admin.tenant.idp.override). Without it the claims are listed with no field to claim one and no control to remove one.

Before you start

  • A claim is created unverified, and an unverified claim routes nothing. Your tenant cannot verify its own claim: a platform administrator verifies it once your organization's ownership of the domain is established.
  • Your tenant's own identity provider can be enabled only once the tenant holds at least one verified domain.
  • Claiming a domain is available on a SaaS deployment only. On a customer-operated deployment a tenant's email domains take no part in sign-in: federated sign-in is admitted against the deployment's own verified domains, which the platform operator declares, and your provider can be enabled once the deployment holds at least one. There the section reads Email domains have no effect on this deployment and offers no field to claim one; a domain already listed can still be removed.
  • A domain is a multi-label host name such as example-bank.com, without the @. It is stored lowercased, so Example-Bank.com and example-bank.com are the same claim.
  • Claiming and removing ask for a recent sign-in. If yours is too old, the console asks you to confirm who you are before it continues.
  • On a SaaS deployment, a platform operator working inside your tenant under a support-access session cannot claim a domain: a verified domain admits federated sign-in for every address on it.
  • On a customer-operated deployment, removing a listed domain needs identity federation delegated to your tenant by the platform operator.

Steps

  1. Open Settings and select the Integrations tab.
  2. On the Identity federation row, select Manage.
  3. Find Verified email domains.
  4. To claim a domain, enter it in the field labelled Email domain to claim and select Claim domain.
  5. Ask your platform administrator to verify the claim. On a customer-operated deployment there is nothing to claim: ask the platform operator to declare the domain among the deployment's verified domains instead.
  6. To remove a claim, select the bin icon on its row (Remove domain). The dialog of the same title names the domain; confirm with Remove domain.

What you see when it worked

A claim appears in the list marked Unverified, and the console confirms Domain claimed. Once a platform administrator verifies it, the row reads Verified, with the method of verification beside it. A removed claim leaves the list, with Domain removed. Both are recorded in the audit trail. Once verified, the domain counts toward enabling your identity provider and routes sign-in for its addresses.

If it fails

A refused claim is shown above the field, with the domain you typed still there. A refused removal is shown inside the dialog, which stays open.

What you see Cause What to do
The domain is refused as invalid The value is not a valid multi-label host Enter the part of the address after the @, for example example-bank.com
A refusal saying the domain is already claimed Your tenant already claimed this domain Nothing to do
This operation is not available while acting on behalf of a tenant. A platform operator in a support-access session tried to claim it on a SaaS deployment The tenant's own administrator claims it
A refusal saying identity federation is not delegated to your tenant On a customer-operated deployment, the platform operator has not delegated identity federation to your tenant Ask your platform operator to delegate it
403 deployment-not-supported on a claim through the API The deployment is customer-operated, where a tenant's email domains take no part in sign-in Ask the platform operator to declare the domain among the deployment's verified domains
A removal refused as not found The claim no longer exists in your tenant Close the dialog and reload the page to read the current list
The provider's enable step shows Declare and verify at least one email domain On a SaaS deployment, no claim of your tenant is verified yet; on a customer-operated deployment, the deployment declares no verified domain On SaaS, claim a domain and have it verified; on a customer-operated deployment, ask the platform operator to declare one

Without the console

Surface How
API POST /api/v3/admin/tenants/{tenantId}/idp/email-domains with {"domain": "example-bank.com"} (operation createEmailDomain)
API DELETE /api/v3/admin/tenants/{tenantId}/idp/email-domains/{id} (operation deleteEmailDomain)

GET on the same collection (operation listEmailDomains) answers appliesToSignIn and domains. appliesToSignIn is the server's verdict: true on a SaaS deployment, false on a customer-operated one, where a claim is refused 403 deployment-not-supported and a listed domain can only be removed. Each entry of domains states verified, with the method and time of verification once verified.

No ankasecure-km command and no Admin SDK method manage email domains.