Federation

Federation means trusting another system to tell you who someone is, or telling another system yourself. It is how Better IAM fits into the identity systems around it.

Your customers already have identity systems. A company that uses Okta or Microsoft Entra ID wants its people to sign in with those accounts, wants its directory to create and remove accounts in your product, and wants former employees to lose access everywhere the day they leave. Your own applications and APIs, in turn, want to rely on Better IAM for sign-in instead of handling passwords themselves. Standard protocols make each of these connections work without custom integration code on either side.

The protocols in plain words

An identity provider (IdP) is the system that knows who a person is and signs them in: Okta, Microsoft Entra ID, Google Workspace, ADFS, or Better IAM itself. The application that trusts the IdP's answer is called the service provider in SAML and the relying party in OpenID Connect.

• OAuth 2.0 lets one application get a limited, revocable token for an account at another service, without ever seeing that account's password. OpenID Connect (OIDC) is a layer on top of OAuth that adds a signed ID token saying who signed in. Together they are the modern standard for "sign in with another account" and for API tokens. Google, GitHub, Microsoft, and every enterprise IdP speak them.
• SAML 2.0 (Security Assertion Markup Language) is the older, XML-based single sign-on (SSO) standard. Many enterprise IdPs and IT teams still prefer it.
• SCIM 2.0 (System for Cross-domain Identity Management) is a REST API for creating, updating, and removing user accounts and groups in another system. It automates the "joiner, mover, leaver" lifecycle.
• The Shared Signals Framework (SSF) lets one system push security events to others as they happen. It has two event profiles: CAEP (Continuous Access Evaluation Profile) for session events such as "this session was revoked", and RISC (Risk Incident Sharing and Coordination) for account events such as "this account was disabled".

The OAuth pages also use a few extensions. Each one is a published internet standard, identified by its RFC (Request for Comments) number:

Who configures what

Your team chooses which protocols to enable and mounts each one once, in code. After that, most connections are created at runtime, per organization, by that organization's administrator (usually the customer's IT team) through your admin UI, the console, or a script. No deployment is needed when a new customer connects.

Which protocol for which job

Start from the job you need done. Each row names the protocol, the factory function that creates its service, and the page that covers it.

How the data flows

Better IAM sits between your customers' identity systems and the applications that rely on you. Information comes in on the left and goes out on the right:

Inbound protocols (OIDC and SAML sign-in, SCIM in) change identities, groups, and sessions. Outbound protocols (the OAuth provider, SCIM out, Shared Signals) read that state and keep the systems downstream of you consistent with it. An offboarding in the customer's directory therefore reaches every connected application: see Offboarding end to end.

Mount a protocol

Each protocol is a separate package that uses the same store, verified credential resolution, and authorization as the rest of Better IAM. Importing the umbrella's main entrypoint does not activate any of them: you configure and mount each protocol you need, so nothing is exposed that you did not ask for.

import { createScimService } from 'better-iam/scim';

// Every factory takes the host callbacks plus its own options (see each protocol's page).
const scim = createScimService({ ...iam.protocolHost });
iam.useProtocol(scim);

• iam.protocolHost is the bundle of trusted callbacks a protocol needs from your instance: the store, credential authentication, authorization checks, session validation, identity-attribute validation, and two callbacks that write to the directory. completeAuthentication turns a verified external identity into a session, and syncRoleMappings turns a directory group into role bindings. Spread it into every factory.
• iam.useProtocol(service) mounts a protocol service under its base path, so the IAM handlers route its requests to it.
• iam.handler(request) is the Fetch-compatible handler (for Next.js, Hono, SvelteKit, and similar). It dispatches every mounted protocol.
• iam.nodeHandler(req, res) is the Node http handler. It does the same, and it can also serve protocols that need Node's own request and response objects. The OAuth authorization server is one of them, so it needs a Node HTTP server rather than a Fetch-only runtime.

When a protocol is mounted through IAM, a successful federated sign-in sets the standard IAM session cookie, so the rest of your application sees an ordinary signed-in user.

For mount paths behind frameworks and proxies, see Protocol mounts.

Shared guarantees

Federation accepts input from systems you do not control, so every protocol package follows the same safety rules:

• Explicit linking. External identities are keyed by tenant, provider, issuer, and subject. Federation never merges accounts because an email address matches, because whoever controls an email setting at another provider would otherwise control the account.
• HTTPS everywhere. Configured endpoints, callbacks, receivers, and downstream services must use HTTPS. allowInsecureLocalhost: true permits plain HTTP to loopback addresses for local development only.
• Secrets at rest. Client secrets, protocol artifacts, receiver headers, and downstream tokens are encrypted. Tokens Better IAM issues are stored as hashes and shown once.
• Audited. Connection changes, provisioning, consents, token exchanges, and syncs append events to the tamper-evident audit chain.

Packages

Install them individually, or use the better-iam/oauth, better-iam/saml, and better-iam/scim subpaths of the umbrella package. All factories are server-only.

Pages in this section

Protocol references

The protocol engines Better IAM builds on, and the SCIM specification, for when you need the underlying details:

• oidc-provider documentation, which powers the authorization server
• oauth4webapi, which powers OAuth and OIDC sign-in
• Node-SAML, which powers SAML validation
• SCIM protocol, RFC 7644