Identity Federation
What this screen is for
This screen hands sign-in for people over to your own corporate identity provider. It is reached from Access & Identity → Identity Federation, and it configures the deployment-wide connection: the provider itself, which of its groups and which e-mail addresses map to which ANKASecure role, which e-mail domains may complete a login, and a read-only view of the deployment's federation posture.
It is not a list of settings. Five of its rows are catalogue values and they are all read-only; everything you actually decide here lives in the platform's own tables and has a declare, test, enable lifecycle of its own. The Configuration tab holds that lifecycle; an Activity tab beside it shows what has been changed, if you hold an audit permission.
There is one connection per protocol and one deployment: three slots — OIDC, SAML, LDAP — and at most one provider in each. A tenant that runs its own provider declares it from inside that tenant, and this screen has no per-tenant tab for that reason.
What must exist first
- The platform context. Every endpoint behind this screen refuses a token that does not carry the platform tenant, identically and without saying why.
- The permission to read identity-provider configuration, which fills the slots, the mappings, the admission rules and the domains.
- The permission to manage identity-provider configuration, which the platform requires for every write here — and also for Test connection and for the pre-flight validation, because both reach out to your provider on your behalf. Every control on this screen, including the group-to-role mappings and the admission rules, follows this same permission; the platform-configuration write plays no part, and holding it without this one leaves the controls disabled.
- Your provider, reachable over HTTPS from the platform, and — for
LDAP— anldaps://URL. A plain LDAP bind is refused outright.
Decisions you make here
Declaring a provider
An empty slot reads Not configured and offers Add OIDC provider, Add SAML provider or Add LDAP provider, which opens a wizard. A configured slot shows the protocol, its live state, a summary of the configuration that matters for that protocol, and Test connection, Edit, Enable, Disable and Delete.
Declaring never enables. A newly declared provider reads Not activatable yet and sits in front of nobody until you enable it explicitly. The secret you supply is write-only: it is never returned, never re-rendered and never resubmitted, so editing a provider and saving with the secret field empty keeps the stored one.
Testing before you enable
Test connection runs the whole check the login path will run, from inside the platform, and records the verdict. For OIDC it fetches the discovery document, refuses a provider whose advertised issuer is not the one you configured, then checks the authorization, token and key-set endpoints — and the optional end-session endpoint — against that provider's own allowed-host list before fetching the key set. That is deliberately the same set the sign-in path validates, so a green test predicts a working login rather than answering a narrower question.
For SAML the test fetches the metadata, parses it safely and asserts the first signing certificate is currently valid. For LDAP it binds and does a shallow search under the base DN, trusting the certificates you configured on that provider rather than the platform's default trust store, and returns a sample of the group values it saw.
A failure it can classify comes back as a verdict you can act on, not as a generic outage. Editing the provider clears the verdict, so a provider whose configuration changed after a passing test is untested again.
Enabling
Enable becomes usable when the platform says the provider is ready, and the screen lists what is missing when it is not. Three things are checked: the last test passed for the current configuration; at least one e-mail domain is declared; and, for OIDC only, you have declared whether that provider's e-mail-verification claim is trusted. The third is a decision, not a formality — leaving it undeclared is not the same as declaring it untrusted, and only the second is treated as an answer.
Approving a provider for platform sign-in
An OIDC or SAML provider shows whether it is Approved for platform sign-in. Approving it declares that the provider enforces phishing-resistant multi-factor authentication for every platform administrator it authenticates. The dialog shows that statement, and Approve stays disabled until you confirm it; the confirmation is recorded with your name and the time.
For platform administrators the approval is the whole decision: the platform adds no factor after an approved provider and does not grade how it authenticated them. Withdraw approval stops platform administrators signing in through it; tenant members keep doing so.
Platform administrators sign in only through approved providers. Approving is the step to take first when platform administrators sign in through this provider. It needs the permission to manage the platform authentication policy. Withdrawing the last approved provider is refused while platform administrators sign in through the identity provider only.
Trusting the provider's multi-factor authentication
An OIDC or SAML provider also answers whether its MFA is trusted: Do not trust this provider's MFA, the default, or Trust this provider's MFA. It decides how a tenant administrator, anyone whose roles allow a change, signs in through it. Members who only read, and platform administrators, are not affected.
While the provider is not trusted, an administrator who signs in through it then also confirms with a passkey or an authenticator app code, or adds one. While it is trusted, the platform asks the provider for MFA, and the provider's sign-in is enough when it proves it: the OIDC amr claim, or the SAML authentication context class. When it does not, the passkey or code is still asked.
Choose Trust this provider's MFA only once the provider enforces MFA for your administrators and states it in its token or assertion. Until administrators hold a passkey or code of their own, anyone holding their password at an untrusted provider can add their first one, so have them register one early. For SAML, Multi-factor authentication class names the class it states when that is not https://refeds.org/profile/mfa; set the class it really issues, because a provider asked for a class it cannot meet refuses the sign-in.
Editing what the provider is trusted to assert, the class included, returns it to not trusted; mark it trusted again in a separate edit. While quorum approval is on, marking it trusted waits for the approvers; withdrawing never does. An LDAP directory has no such choice.
Group to role mapping, and admission by e-mail or domain
Mapping is deny by default. A federated identity that resolves to no role is refused: no account is created and no token is issued. Two axes feed that decision and they are combined, not ranked. Group to role mapping maps a group string your provider emits to an ANKASecure role. Email & domain admission maps a full e-mail address, or a domain, to a role. A match on either grants that role.
A role you may not assign in the platform tenant is refused at declaration time, on both axes, with the reason and the categories that are allowed.
Verified domains
On a deployment you operate, declaring a domain is verifying it: there is no DNS challenge, no token to publish and no pending state. The platform records you as the party who declared it, from your session rather than from anything you type. The two-party claim-then-verify flow, where a tenant claims a domain and the platform confirms it, is not offered on a customer-operated install.
Only a login whose e-mail domain is in this set is admitted, matched as exact equality on the normalised name and never as a suffix — acme.com does not admit evil-acme.com, and it does not admit mail.acme.com either.
Domain guards are a separate and narrower control on the same tab. Where the admission rules above grant a role, a guard grants nothing: once a provider has at least one guard, only identities whose e-mail domain is on that list may finish signing in.
Deleting a mapping or an admission rule, or adding a domain guard, is refused when it would leave no platform super administrator able to sign in, and nothing changes. A super administrator linked to the provider keeps that way in while their e-mail domain passes every guard and an e-mail or domain rule matches them, or the provider keeps at least one group mapping: the groups your provider sends are known only when the person signs in, so any remaining mapping counts.
Posture
The last tab reports the deployment's federation posture and cannot be edited from here: whether LDAP providers are refused a plaintext bind in production, whether single sign-on is enforced for newly provisioned tenants, and whether a federated principal is provisioned on first successful login.
The browser-facing edge origin is reported here too. The platform derives the OAuth 2.0 redirect URI and the SAML assertion-consumer URL from it, on the server, which is why it is read-only on this plane: repointing it repoints the address your provider sends the browser back to.
How it relates to other screens
A federated identity only becomes useful once it lands on an account with roles. Both are administered elsewhere, and so is binding an existing local account to a federated identity:
Machine identities are a different subsystem with a different screen — a workload presents a token its own issuer minted, and nothing on this page applies to it:
How platform administrators sign in, and which sign-in methods every tenant may admit, is decided on its own screen:
The rest of the sign-in configuration — token lifetimes, lockout, session cookies — is the group this screen sits in, and every external system this deployment is wired to is on the topology screen: