Skip to content

Restrict who may enter through the identity provider

Decide which people your tenant's identity provider may admit: grant a role to a specific email address or to everyone of an email domain, and limit sign-in through the provider to the domains you allow.

Who can do it

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

  • The section Who may enter through your identity provider is shown only to someone who can read both the providers (admin.tenant.idp.read) and the admission rules (admin.tenant.idp.mapping.read).
  • Adding and removing an email or domain rule needs the permission to manage federation mappings (admin.tenant.idp.mapping.manage).
  • Adding and removing a permitted domain needs the permission to configure identity federation (admin.tenant.idp.override).

Without a write permission the lists are shown with no form to add an entry and no control to remove one.

On a SaaS deployment, a platform operator working inside your tenant under a support-access session cannot add an email or domain rule, and cannot add or remove a permitted domain. Your tenant's own administrator does.

Before you start

  • Your tenant has its own identity provider declared. See Sign in with your company's identity provider. Until one is, the section reads Declare a provider before admitting users by email or domain.
  • Three blocks, for two different questions:
    • Email to role and Domain to role grant a role on a match: one full address, or every address of a domain.
    • Domain guard grants nothing. It is an allowlist per provider: a provider with no permitted domain lets every domain past the guard; once it has at least one, only federated identities whose email domain is in its list may complete sign-in. The provider's first permitted domain therefore narrows who may enter, each further one admits its own domain as well, and removing the last one lets past again every domain it had kept out. Past the guard, the rules and group mappings still decide who is admitted and with which role.
  • You can add a rule only for a role whose every permission you hold yourself, because the rule confers the role on everyone it matches.
  • The role list of Domain to role offers no role carrying a platform or wildcard permission. The role list of Email to role offers every role that can be assigned to people in your tenant.
  • A match value or permitted domain cannot contain a wildcard (*) or control characters.
  • Adding 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 customer-operated deployment, the platform operator must have delegated identity federation to your tenant.

Steps

  1. Open Settings and select the Integrations tab.
  2. On the Identity federation row, select Manage.
  3. Scroll to Who may enter through your identity provider.
  4. To admit one address, under Email to role choose the Provider, enter the Email address, choose the ANKASecure role, and select Add rule.
  5. To admit everyone of a domain, under Domain to role choose the Provider, enter the Domain, choose the ANKASecure role, and select Add rule.
  6. To limit sign-in through a provider to the domains you allow, under Domain guard choose the Provider, enter the Permitted domain, and select Add rule.
  7. To remove an entry, select the bin icon on its row (Remove email rule, Remove domain rule or Remove permitted domain). The dialog of the same title names the entry; confirm with Remove email rule, Remove domain rule or Remove permitted domain.

What you see when it worked

The entry appears in, or leaves, its block's list, and the console confirms the change: Email rule added, Domain rule added, Permitted domain added, or the matching … removed. Every change is recorded in the audit trail and applies from the next federated sign-in. Domains are stored normalized, so Example-Bank.com and example-bank.com are the same permitted domain.

When your tenant's quorum approval is on and the admitted role confers approval rights, adding the rule shows Waiting for approval with Open the quorum request: the rule is not in the list until your approvers decide.

If it fails

A refused addition is shown above the block's form, with what you typed still there. A refused removal is shown inside the dialog, which stays open.

What you see Cause What to do
The address or domain is refused as malformed It is not a valid address or domain, or contains a wildcard Correct the value
The role is refused as service-to-service only, or as not assignable in a tenant of this type The role is not meant for people in your tenant Choose a tenant role meant for people
A domain rule is refused for its role The role carries a platform-scope or wildcard permission Choose a narrower role, or admit the person with an email rule
A refusal by the subset rule, naming the missing permissions You do not hold every permission the admitted role carries Ask someone who holds them, or admit a narrower role
A refusal saying your edition does not include tenant-configured federation, on adding a rule or removing a permitted domain Your edition does not include it. Removing the last permitted domain re-admits the domains it kept out, so it is held to the edition; adding a permitted domain is not Contact your account manager
This operation is not available while acting on behalf of a tenant., on adding a rule or on adding or removing a permitted domain On a SaaS deployment, a platform operator in a support-access session cannot add an email or domain rule, or change the permitted domains: a permitted domain added beside another, or the removal of the last one, admits domains for every later sign-in, beyond the session The tenant's own administrator makes the change
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
A refusal saying the rule or permitted domain already exists The same entry is declared Nothing to do

A role that a rule still names cannot be deleted: remove the rule first. Deleting the provider deletes its rules and permitted domains with it.

Without the console

Surface How
API POST /api/v3/admin/tenants/{tenantId}/idp/admission-rules (operation createAdmissionRule)
API DELETE /api/v3/admin/tenants/{tenantId}/idp/admission-rules/{ruleId} (operation deleteAdmissionRule)
API POST /api/v3/admin/tenants/{tenantId}/idp/domain-guards (operation createDomainGuard)
API DELETE /api/v3/admin/tenants/{tenantId}/idp/domain-guards/{guardId} (operation deleteDomainGuard)

An admission rule's body names the provider (idpConfigId), the ruleType (EMAIL or DOMAIN), the matchValue and the ankaRoleName; a domain guard's names the provider and the domain.

On a SaaS deployment, createAdmissionRule, createDomainGuard and deleteDomainGuard called under a support-access impersonation session answer 403 impersonation-operation-forbidden.

No ankasecure-km command and no Admin SDK method manage admission rules or domain guards.