Auth & Identity — Integration Guide

Overview

The auth service (Rust) is the single source of truth for platform identity. It handles user registration, session management, multi-factor authentication, corporate SSO (SAML 2.0), and SCIM provisioning token lifecycle — powering both consumer and enterprise identity flows.

Port: 3008 · Framework: Axum + async-graphql · Database: PostgreSQL + Redis

Authentication Methods

The auth service implements a passwordless-first identity strategy. Passwords are intentionally excluded by design.

For detailed MFA (TOTP, SMS, backup codes) and Passkey integration, see MFA & Passkeys.

SAML 2.0 — Enterprise SSO

The auth service acts as a SAML Service Provider (SP), receiving assertions from corporate IdPs to authenticate Organization members.

Configuration

Organization admins configure SAML via GraphQL:

mutation ConfigureSaml($orgId: ID!, $input: ConfigureSamlInput!) {
	configureSaml(orgId: $orgId, input: $input) {
		orgId
		entityId
		ssoUrl
		certificate
		attributeMapping {
			email
			firstName
			lastName
		}
	}
}

SAML Endpoints

Login Flow

1. Visitor clicks "Login with SSO" → redirected to IdP
2. IdP authenticates → posts SAML assertion to /auth/saml/:org_id/acs
3. Auth service parses assertion → finds or creates user by email
4. Session + refresh tokens issued → Visitor redirected with active cookies
5. AuthMethod::Saml audit event logged

GraphQL API

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

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

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

# Test connectivity
mutation {
	testSamlConfig(orgId: "org-01") {
		success
		message
	}
}

For the full feature overview including SCIM provisioning, see Corporate Identity (SAML & SCIM).

SCIM Token Management

The auth service manages SCIM bearer tokens that the dedicated SCIM service uses for authentication. Tokens are stored as SHA-256 hashes — the raw value is returned once on generation and never persisted.

# Generate token (raw value shown ONCE)
mutation {
	generateScimToken(orgId: "org-01", label: "Okta SCIM") {
		token # ← copy immediately
		id
		label
	}
}

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

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

Identity Checks (REST)

Before attempting a guest lookup or signup, use these REST endpoints to check if an account already exists.

Response:

{
	"exists": true,
	"userId": "uuid-v4-identifier"
}

Session Management

Dual-Token Strategy

Key Endpoints

GraphQL API

Queries

# Current user profile
query {
	me {
		id
		username
		email
		phone
		emailVerified
		createdAt
	}
}

# Session status
query {
	mySession {
		isAuthenticated
		userId
		deviceId
		hasRefreshToken
	}
}

# Device list
query {
	myDevices {
		id
		deviceName
		deviceType
		trusted
		isCurrent
		lastSeenAt
	}
}

# Security events
query {
	mySecurityEvents(limit: 20) {
		eventType
		severity
		description
		ipAddress
		createdAt
	}
}

# MFA status
query {
	mfaStatus {
		totpEnabled
		smsEnabled
		backupCodesRemaining
	}
}

# SAML config (requires MANAGE_SSO)
query {
	samlConfig(orgId: "org-01") {
		entityId
		ssoUrl
		certificate
	}
}

# SCIM tokens (requires MANAGE_SSO)
query {
	scimTokens(orgId: "org-01") {
		id
		label
		lastUsedAt
	}
}

Mutations

# Device management
mutation { trustDevice(deviceId: "...") { id trusted } }
mutation { untrustDevice(deviceId: "...") { id trusted } }
mutation { renameDevice(deviceId: "...", name: "Work Laptop") { id deviceName } }
mutation { revokeDevice(deviceId: "...") }

# WebSocket token (for uChat)
mutation { issueWsToken { token expiresIn } }

# Guest tokens
mutation { generateGuestToken(input: { scope: "malet:123" }) { token expiresAt } }
mutation { convertGuestToUser(guestTokenId: "...") { userId } }

# SAML configuration (requires MANAGE_SSO)
mutation { configureSaml(orgId: "...", input: { ... }) { orgId entityId ssoUrl } }
mutation { deleteSamlConfig(orgId: "...") }
mutation { testSamlConfig(orgId: "...") { success message } }

# SCIM tokens (requires MANAGE_SSO)
mutation { generateScimToken(orgId: "...", label: "Okta") { token id label } }
mutation { revokeScimToken(orgId: "...", tokenId: "...") }

MFA (Multi-Factor Authentication)

The auth service supports TOTP (authenticator app), SMS OTP, and backup codes as second factors. MFA is enforced across all login methods: email OTP, OAuth, passkeys, mobile, and SAML.

See MFA & Passkeys for the full integration guide with browser-side code examples.

Internal Workflow: Guest Redirection

When a user requests guest order access (via murchases), the system performs the following checks:

1. Identity Check: murchases calls auth via the REST API above.
2. Fail-Fast: If an account exists for the provided email/phone, the system prompts for Login instead of sending a Guest OTP.
3. OTP Dispatch: If no account exists, a 6-digit code is sent via the alerts subgraph.

Database Schema

File Reference

Testing

cd apps/auth && cargo test

Environment Variables

Related

• Corporate Identity (SAML & SCIM) — Enterprise SSO login via SAML 2.0 and automated provisioning via SCIM 2.0
• MFA & Passkeys — TOTP and WebAuthn integration guide for the auth service
• SCIM — Provisioning Engine — Dedicated SCIM 2.0 service for IdP-driven user lifecycle management
• uChat — E2EE Messenger — Real-time messaging service that depends on auth for identity context
• Privacy & Security APIs — Session management, data export, and security event logs