Registration Handler

A Salesforce Apex component that runs when an external identity signs in through federation. It decides whether to create, match, or update the local user record, which makes it a lifecycle control point as much as an authentication component.

Expanded Definition

A registration handler is the lifecycle control in federated identity flows that determines whether an external identity should be created as a new local user, matched to an existing record, or updated with new attributes. In Salesforce, it sits at the point where authentication outcome turns into local identity state, so it affects trust, access, and account hygiene at the same time.

Definitions vary across vendors because some platforms treat registration logic as a simple account-mapping hook, while others expose it as a policy layer for provisioning, linking, and attribute governance. In NHI and agentic AI environments, that distinction matters because a registration decision can silently create durable access for a non-human actor, not just a person. The control should therefore be understood as part of identity lifecycle governance, not merely sign-in orchestration.

Where the term is used loosely, teams may confuse federation with automatic trust, even though the handler still needs explicit rules for uniqueness, proof of prior identity, and attribute normalization. The most common misapplication is auto-creating local users from any incoming assertion, which occurs when federation is assumed to be equivalent to authorization.

Examples and Use Cases

Implementing a registration handler rigorously often introduces operational friction, requiring organisations to balance fast onboarding against the risk of account sprawl, duplicate identities, and weak attribute control.

• A partner authenticates through SAML, and the handler maps the assertion to an existing user only if email, issuer, and tenant identifiers all match approved patterns.
• A customer signs in through social federation, and the handler creates a local profile only after a verified invitation and domain policy check.
• An internal automation identity uses a federated broker, and the handler prevents silent user creation unless the service account is pre-approved and tagged for lifecycle ownership.
• A Salesforce org updates department and role attributes at sign-in, but only from trusted claims sources that have been normalized against local policy.
• During review of identity sprawl, teams compare handler rules with the lifecycle and secret-management risks described in the Ultimate Guide to NHIs and with federation guidance in the NIST Cybersecurity Framework 2.0.

In practice, the registration handler is often extended to enforce business rules for account linking, but no single standard governs the exact policy model yet.

Why It Matters in NHI Security

Registration handlers are security-critical because they decide whether an external assertion becomes a persistent local identity with access rights, attributes, and downstream entitlements. When that decision is too permissive, organisations create hidden privilege paths, duplicate identities, and orphaned accounts that are difficult to revoke later. NHI Management Group research shows that 80% of identity breaches involved compromised non-human identities such as service accounts and API keys, which underscores how lifecycle mistakes become breach paths, not just admin issues. The Ultimate Guide to NHIs also notes that 97% of NHIs carry excessive privileges, making poor registration logic a multiplier for blast radius.

For governance, the handler should be reviewed alongside federation policy, access recertification, and offboarding controls, because a bad create-or-match decision can outlive the original sign-in event. Its operational value is highest when tied to NIST Cybersecurity Framework 2.0 identity and access outcomes rather than treated as a purely technical callback. Organisations typically encounter duplicate accounts, unauthorized access, or failed offboarding only after a federation incident or account-takeover event, at which point registration handler logic becomes operationally unavoidable to address.

Related resources from NHI Mgmt Group

• How should security teams govern partner application registration in OAuth ecosystems?
• What is the difference between OpenID Federation registration and DCR?
• When does manual client registration create more risk than it reduces?
• Why do partner APIs still need cryptographic trust anchors after registration?