Developer Docs

Enterprise Security & Identity

The $mall platform provides deep integrations with corporate identity providers (IdPs) like Okta, Azure AD, and JumpCloud ensuring secure identity management at scale. This functionality is centered around SAML 2.0 for Single Sign-On and SCIM 2.0 for directory synchronization.

1. SAML Single Sign-On

The SAML 2.0 (Security Assertion Markup Language) configuration enables Organization members to authenticate using their corporate IdP, bypassing local credentials.

Configuration (`SamlConfig`)

Each organization can maintain a single SamlConfig entity:

Field Type Description
entityId String The issuer URI from the IdP.
ssoUrl String The HTTP-POST binding endpoint where authentication requests are addressed.
certificate String Public X.509 certificate used to verify assertion signatures. Stored securely and masked in API queries.
enabled Boolean Activates the integration. Must be toggled on to process assertions.

Attribute Mapping

SAML assertions must map specific traits back to the platform account.

  • Email Attribute (Default: email): Critical for account matching or auto-provisioning.
  • Display Name (Optional): Extracted on first provision if provided.
  • Role Hint (Optional): An attribute describing the local OrgRole to assign to the user.

Provisioning Fallback

If no Role Hint is provided, users auto-provisioned via SAML will fall back to the defaultOrgRole defined on the SamlConfig (usually MEMBER or VIEWER).

2. SCIM Directory Synchronization

SCIM 2.0 (System for Cross-domain Identity Management) allows automated user lifecycle management. When employees are hired, promoted, or terminated in the central IdP, their access to the platform is automatically provisioned, updated, or revoked without manual intervention.

Token Architecture (`scimTokens`)

SCIM clients require a Long-Lived Bearer Token to authenticate against the /scim/v2 endpoints.

  • Tokens are generated via the generateScimToken mutation.
  • The raw token (token payload) is returned only once upon generation. A hashed version (token_hash) is stored in the database.
  • Tokens can be explicitly revoked by Organization Administrators via revokeScimToken.
Feature Detail
Auto-Revocation Old tokens can be revoked immediately, terminating directory sync processes.
Last Used Tracking Features a lastUsedAt timestamp for auditing when the IdP last successfully queried the tenant.
Multiple Tokens Supports multiple active tokens to allow rolling migration between different IdP systems or environments.

Developer Implementation

The frontend implementation relies heavily on standard Svelte 5 stores and forms. The APIs reside within src/lib/queries/security.ts. All Enterprise security features require PLATFORM_ADMIN or Organization OWNER status.

Security Note

WARNING

SAML certificate updating logic uses an undefined payload technique. certificate is omitted from updateSamlConfig form submissions unless it is being completely overwritten by the administrator. This is critical as the GET_SAML_CONFIG query intentionally masks the certificate, which would cause an invalid key to be saved if sent back unmodified.