Configure enterprise SSO and SCIM with Own Auth

SAML and SCIM solve different enterprise tasks. SAML lets a member authenticate through an organisation identity provider. SCIM lets that identity provider create, suspend, restore, and remove access for users in one organisation. Pair them when the customer needs both controlled provisioning and single sign on.

Enable both capabilities

Apply the Own Auth migrations before configuration. SAML uses the separately imported protocol implementation so applications without SAML do not load its XML dependency. SCIM is enabled through the auth options. Both use the same Own Auth storage and organisation authorization.

import { createOwnAuth } from "own-auth";
import { createSaml } from "own-auth/saml";

export const auth = createOwnAuth({
  baseUrl: "https://auth.example.com",
  tokenPepper: process.env.OWN_AUTH_TOKEN_PEPPER!,
  saml: createSaml(),
  scim: {},
});

Create the SAML connection

Only an organisation owner can manage a connection. The first connection also requires that owner to retain a non SAML sign in method, which prevents one configuration mistake from locking out every owner. Use the identity provider metadata values and trusted signing certificates supplied for that customer.

const samlConnection = await auth.saml.createConnection({
  organisationId,
  actorUserId: currentUser.id,
  name: "Company SSO",
  idpEntityId: "https://idp.example.com/saml/metadata",
  ssoUrl: "https://idp.example.com/saml/sso",
  idpCertificates: [process.env.IDP_SIGNING_CERTIFICATE!],
  attributeMapping: {
    email:
      "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress",
    name:
      "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name",
  },
});

Give the identity provider the connection specific metadata URL returned for this setup. Keep old and new signing certificates together during certificate rotation, then remove the old certificate after the provider completes its change. Own Auth validates signatures, issuer, audience, destination, recipient, request identity, time limits, and assertion replay state.

Create the SCIM connection and token

Create one SCIM connection for the same organisation. Its default role must be a configured non owner role. Create a connection token and give the raw value to the identity provider once. Own Auth stores only its peppered hash.

const scimConnection = await auth.scim.createConnection({
  organisationId,
  actorUserId: currentUser.id,
  name: "Company provisioning",
  defaultRole: "member",
});

const createdToken = await auth.scim.createToken({
  connectionId: scimConnection.id,
  actorUserId: currentUser.id,
  name: "Identity provider",
});

deliverOnceToIdentityProvider(createdToken.rawToken);

Mount the SCIM handler separately

SCIM requests authenticate with the connection bearer token, not an application session. Mount the dedicated handler at /scim/v2/* and pass only a client address resolved through the trusted proxy configuration.

import { createOwnAuthScimHandler } from "own-auth/scim";

import { auth } from "./auth";

export const scimHandler = createOwnAuthScimHandler(auth, {
  getRequestContext(request) {
    return {
      ipAddress: getTrustedClientIp(request),
      userAgent: request.headers.get("user-agent") ?? undefined,
    };
  },
});

Pair SAML with SCIM

Pair the two connections only when they belong to the same organisation. After a SAML response passes every signature and protocol check, Own Auth can resolve the active SCIM resource by exact normalized email. The first successful match can mark the SCIM created user's email verified.

await auth.scim.updateConnection({
  connectionId: scimConnection.id,
  actorUserId: currentUser.id,
  samlConnectionId: samlConnection.id,
});

Explicit account linking remains the safest default. A SCIM email that already belongs to an Own Auth user returns a conflict instead of taking over the account. After that user authenticates through an existing method, an organisation owner can call auth.scim.linkUser with the exact connection and workforce identifiers.

Deprovision organisation access only

Setting a SCIM User to inactive suspends its organisation membership. Deleting the resource removes that membership and keeps a tombstone that reserves its workforce identifiers. Neither action deletes the global Own Auth user, disables sessions for other organisations, or removes unrelated memberships.

Restoration is an explicit owner action through auth.scim.restoreUser. It fails when another connection or membership has claimed the identity, when the original role no longer exists, or when the global user is unavailable. The restore operation never overwrites a conflicting resource.

Choose JIT or SCIM ownership clearly

SAML just in time provisioning can create a user and non owner membership on first sign in. SCIM creates access before sign in and can suspend it centrally. When SCIM is the customer directory owner, pair the connections and keep SAML JIT disabled so two independent paths do not compete to create membership.

Own Auth does not accept identity provider groups or roles as organisation owner authority. Map the connection to one configured default role, then use application administration for deliberate role changes. Reassign members and connections before removing a custom role from configuration.

Respect SCIM versions and conditional updates

SCIM responses include a weak ETag derived from the resource version. Send that value in If-Match for conditional updates and deletion. A stale version fails instead of overwriting a concurrent change. Identity provider retries should read the current resource before deciding whether another mutation is still required.

Operate connection credentials

Rotate SCIM bearer tokens by creating a new token, updating the identity provider, confirming successful requests, and revoking the old token. Disabling the connection rejects every token immediately but does not permanently revoke each token. Use token revocation when an old value must never work again.

Before handoff to a customer, test metadata import, signed SAML login, certificate rotation, replay rejection, SCIM discovery, create, filter, update, suspend, delete, restore, token revocation, and the paired SAML login. Confirm that owner roles cannot be provisioned and that logs exclude assertions, certificates, bearer tokens, subjects, relay state, and complete SCIM bodies.