Corporate Identity — SAML & SCIM

Enable enterprise-grade single sign-on (SSO) and automated user provisioning for Organizations on Mallnline. Malet Owners with corporate teams can connect their existing Identity Provider — Okta, Azure AD, Google Workspace, or any SAML 2.0 / SCIM 2.0 compliant provider — to automate member lifecycle management.

How It Works

Corporate Identity has two complementary protocols that work together:

End-to-End Flow

┌──────────────────────────────────────────────────────────────────────┐
│                        Identity Provider (IdP)                        │
│                    (Okta / Azure AD / Google Workspace)                │
└──────────┬───────────────────────────────────┬───────────────────────┘
           │                                   │
           │ SAML Assertion                    │ SCIM REST API
           │ (interactive login)               │ (automated sync)
           ▼                                   ▼
    ┌──────────────┐                    ┌──────────────┐
    │  auth :3008  │                    │  scim :3019  │
    │              │                    │              │
    │  SAML ACS    │                    │  User CRUD   │
    │  Session     │                    │  Group CRUD  │
    │  Creation    │                    │  Discovery   │
    └──────┬───────┘                    └──────┬───────┘
           │                                   │
           │ creates session                   │ creates/updates users
           │ + audit event                     │ + org memberships
           ▼                                   ▼
    ┌──────────────────────────────────────────────┐
    │           Shared Platform Identity            │
    │     Postgres (users) + MongoDB (memberships)  │
    └──────────────────────────────────────────────┘

SAML 2.0 — Single Sign-On

Configuration

Organization admins configure SAML via the Auth subgraph's GraphQL API:

mutation ConfigureSaml($orgId: ID!, $input: ConfigureSamlInput!) {
	configureSaml(orgId: $orgId, input: $input) {
		orgId
		entityId
		ssoUrl
		certificate # masked preview (first/last 20 chars)
		attributeMapping {
			email
			firstName
			lastName
		}
	}
}

Input:

{
	"orgId": "org-enterprise-01",
	"input": {
		"entityId": "https://idp.corp.example.com/saml/metadata",
		"ssoUrl": "https://idp.corp.example.com/saml/sso",
		"certificate": "-----BEGIN CERTIFICATE-----\nMIIC...\n-----END CERTIFICATE-----",
		"attributeMapping": {
			"email": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress",
			"firstName": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname",
			"lastName": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname"
		}
	}
}

SAML Endpoints

Login Flow

1. Visitor clicks "Login with SSO" on the platform
2. Platform redirects to the IdP's SSO URL with a SAML AuthnRequest
3. Visitor authenticates with their corporate credentials (password, MFA, etc.)
4. IdP posts a SAML assertion to /auth/saml/:org_id/acs
5. Auth service:
   • Parses and validates the SAML assertion (Base64 → XML → NameID extraction)
   • Finds or creates the platform user by email
   • Creates or reuses a device record for the session
   • Issues session + refresh tokens (same dual-token strategy as MFA & Passkeys)
   • Logs a Saml audit event
6. Visitor is redirected to the platform with active session cookies

Attribute Mapping

The SAML assertion contains user attributes. The attributeMapping configuration tells the auth service which XML attributes correspond to which platform fields:

If no attribute mapping is configured, the auth service falls back to extracting the NameID element from the assertion as the user's email.

Managing SAML Configuration

# Update an existing config
mutation {
	updateSamlConfig(orgId: "org-01", input: { ssoUrl: "https://new-idp.com/sso" }) {
		orgId
		ssoUrl
	}
}

# Delete a config (disables SSO for the org)
mutation {
	deleteSamlConfig(orgId: "org-01")
}

# Test the config (validates certificate + connectivity)
mutation {
	testSamlConfig(orgId: "org-01") {
		success
		message
	}
}

# View config (certificate is masked for security)
query {
	samlConfig(orgId: "org-01") {
		entityId
		ssoUrl
		certificate
		attributeMapping {
			email
			firstName
			lastName
		}
	}
}

SCIM 2.0 — Automated Provisioning

SCIM handles the automated lifecycle management of users and groups. When an IT admin adds, updates, or removes a user in their IdP, the change is automatically reflected in Mallnline.

For full REST API reference, see the SCIM Subgraph documentation.

Token Management

SCIM tokens are generated via the Auth GraphQL API and scoped to a single Organization:

# Generate a new SCIM token (raw value shown ONCE)
mutation {
	generateScimToken(orgId: "org-enterprise-01", label: "Okta Provisioning") {
		token # ← copy this immediately — never shown again
		id
		label
	}
}

# List active tokens (no raw values)
query {
	scimTokens(orgId: "org-enterprise-01") {
		id
		label
		lastUsedAt
		createdAt
	}
}

# Revoke a token (immediate)
mutation {
	revokeScimToken(orgId: "org-enterprise-01", tokenId: "token-id")
}

Provisioning Operations

Membership Tracking

When users are provisioned via SCIM, their Organization membership is tagged with provisionedBy: "scim":

query {
	organization(id: "org-enterprise-01") {
		members {
			userId
			role
			provisionedBy # "scim" | "saml" | "manual"
		}
	}
}

This allows Organization admins to see which members were added manually vs. automatically by the IdP.

Organization Extensions

Corporate Identity adds several fields and capabilities to the Organizations subgraph:

New Fields

New Permission

Audit Events

All corporate identity operations are logged via the Organization Audit Trail:

Security Model

SAML Security

• Certificates: IdP X.509 certificates are stored as-is (they are public keys, not secrets)
• Assertion validation: Base64 → XML parsing with element extraction and signature verification
• Session creation: Uses the same dual-token strategy as all other auth methods
• Audit trail: Every SAML login is logged with AuthMethod::Saml

SCIM Security

• Zero-knowledge tokens: Raw tokens are never stored — only SHA-256 hashes
• Per-org isolation: Each token is scoped to exactly one Organization
• Instant revocation: Revoked tokens are excluded immediately via partial index
• Usage tracking: last_used_at updated on every authenticated request
• No gateway: SCIM traffic does not pass through the Apollo gateway — direct to the SCIM service

File Reference

Testing

# Auth SAML tests
cd apps/auth && cargo test saml

# SCIM service tests
cd apps/scim && cargo test

Related

• SCIM — Provisioning Engine — Full REST API reference for the SCIM 2.0 service
• Auth & Identity — Identity management service that hosts SAML endpoints and SCIM token management
• MFA & Passkeys — Other authentication methods (TOTP, WebAuthn) that complement SAML SSO
• Organizations & Permissions — Membership, roles, and teams that Corporate Identity provisions into
• Teams & Sub-Groups — SCIM Groups map to Teams via the externalId field
• Custom RBAC — Custom roles that can be assigned to SCIM-provisioned members
• SIEM Event Streaming — Stream corporate identity audit events (SAML logins, SCIM provisioning) to external SIEM platforms