AI Integration

:::info Source Sourced from services/identity-service/AI_INTEGRATION.md in the documentation repo. :::

Companion: ai-gateway-service · 13 Security & AI Safety §8 · DOMAIN_MODEL

1. Scope

Identity-service uses AI in exactly one capacity: adaptive MFA risk classification. Identity-service does not generate content, embeddings, summaries, or any learner-facing AI output.

2. Adaptive MFA Risk Classifier

2.1 Purpose

Decide whether a login attempt should be challenged with MFA based on behavioral and contextual signals. The goal is to reduce friction on recognized devices / contexts while stepping up security on suspicious attempts.

2.2 Classification Target

Input: login attempt context. Output: risk score [0, 100] with categorical reasons.

2.3 Features Used

Feature	Source	Why it matters
Device fingerprint	Device aggregate	New device → elevated risk
IP address	Request	Geolocation, reputation
Geolocation delta from last login	Session history	Impossible travel detection
Time since last successful login	Session history	Long absence → re-verify
Failed attempts in last 24h (same user)	Audit log	Pattern of attack
Failed attempts in last 24h (same IP)	Audit log	Credential stuffing signal
User agent family & version	Request	Unusual UA → potential bot
Time of day vs user's typical pattern	Audit log	Anomalous hour
Tenant's MFA policy strictness	Tenant config	Configurable base threshold

2.4 Model Classes

Two complementary classifiers:

1. Rule-based classifier (always-on baseline):

   • Explicit thresholds, deterministic.
   • Encoded as TypeScript logic in the domain layer.
   • Not an AI call.
   • Produces a baselineRisk score.

2. AI anomaly classifier (ai-gateway-delegated):

   • Unsupervised anomaly detection over the user's historical login pattern.
   • Supplements baseline; not a replacement.
   • Called via POST /api/v1/ai/classify on ai-gateway-service.
   • Returns aiRisk score and categorical reasons.
   • Graceful degradation: if ai-gateway unavailable or budget exceeded, baseline rules alone govern the decision.

2.5 Integration Pattern

// application/services/AdaptiveMFAService.ts
interface AdaptiveMFAService {
  evaluate(ctx: LoginContext): Promise<MFADecision>;
}

interface LoginContext {
  userId: UserId;
  tenantId: TenantId;
  email: Email;
  deviceId?: DeviceId;
  deviceFingerprint?: string;
  ip: string;
  ua: string;
  failedAttempts24h: number;
  lastLoginAt?: ISODate;
  lastLoginGeo?: { country: string; city: string };
  currentGeo?: { country: string; city: string };
}

interface MFADecision {
  required: boolean;
  factors: MFAKind[];         // which factors are acceptable
  riskScore: number;           // 0-100
  riskReasons: string[];       // ['new_device', 'atypical_location', 'anomaly_detected']
  classifierVersion: string;
}

2.6 AI Gateway Call

// infrastructure/ai/AIRiskClassifierAdapter.ts
class AIRiskClassifierAdapter implements AIRiskClassifier {
  async classify(features: LoginFeatures): Promise<AIRiskResult> {
    const response = await this.aiGatewayClient.classify({
      promptId: 'identity.adaptive_mfa.v1',
      promptVersion: this.promptVersion,
      input: {
        features: this.redactPII(features),
      },
      tenantId: features.tenantId,
      budget: { category: 'security', maxCostMicroUSD: 100 },
      timeout: 500, // ms; hard cap — security decisions cannot wait
    });
    return {
      riskScore: response.output.risk_score,
      reasons: response.output.reasons,
      confidence: response.output.confidence,
      traceId: response.traceId,
      provenance: response.aiProvenance,
    };
  }
}

2.7 Fallback Strategy

AI Gateway State	Behavior
Available, budget OK	Use AI + rule baseline; combine with max(ai, rules)
Available, budget exceeded	Rules only; log ai.refused.budget
Unavailable (circuit open)	Rules only; log ai.refused.provider, degraded mode
Latency > 500ms	Abort AI, use rules only

Default safety posture: When in doubt, require MFA. Never lower the rule-based threshold based on AI output.

2.8 PII Handling

Before sending features to ai-gateway:

• Email → SHA-256 hash with tenant salt
• IP address → /24 subnet (IPv4) or /48 (IPv6), not full address
• Geolocation → country + city only; no precise coordinates
• User agent → parsed family/version; no raw string

These redactions are applied at the adapter boundary, not in the domain layer, to keep domain code infrastructure-agnostic.

2.9 Provenance

Every MFA decision produced with AI assistance records:

{
  decisionId: string;
  baselineScore: number;
  aiScore?: number;
  finalDecision: 'challenge' | 'allow';
  classifierVersion: string;
  aiProvenance?: AIProvenance;  // if AI was consulted
  evaluatedAt: ISODate;
}

Stored in audit_log for:

• Post-hoc review of false positives/negatives
• Compliance with "right to explanation" when user disputes an MFA challenge
• Model drift detection over time

3. Bias & Fairness

3.1 Risks

• Geographic bias: Users in regions with less historical data might be over-challenged.
• Device diversity bias: Users with uncommon devices (assistive tech, older phones) might be flagged as anomalies.
• Temporal bias: Night-shift workers flagged as "atypical hour."

3.2 Mitigations

• Classifier trained on per-tenant (or per-cohort) baselines where data volume permits.
• Explicit user-level overrides: users can mark "this device is mine" to suppress future flags.
• Fallback threshold tuning per-tenant: tenants with strong DEI requirements can opt for rule-only mode.
• Quarterly fairness audit: demographic parity on MFA challenge rate (where demographics are known and consented).

4. Human Override

• User override: A challenged user who verifies successfully can mark the session context as "trusted"; future logins from the same context are not challenged.
• Admin override: Tenant admins can disable adaptive MFA entirely (all logins challenged uniformly) or force it on for all sensitive scopes.
• Dispute flow: Users may dispute a spurious challenge via support; surfaces to tenant admin for review. Admin response feeds back into classifier (with consent).

5. Non-AI Uses — Explicit Non-Goals

Identity-service does not use AI for:

• Password strength assessment (uses rule-based policy only)
• Account recovery decisions (rule-based + manual review)
• Generating welcome emails (notification-service handles templates)
• Summarizing login history (no AI-generated text in identity UX)
• Translating UI strings (i18n is a platform concern)
• Any learner-facing content

6. Local Inference

Identity-service does not run on-device AI models. The adaptive MFA classifier is server-side only because:

• Fresh training data is centralized.
• Avoids client-side model tampering risk.
• Decisions happen during online authentication anyway.

7. Budget & Quotas

• Budget category: security (highest priority, least likely to be throttled).
• Per-login cost ceiling: 100 microUSD.
• Per-tenant monthly ceiling: configurable; default 1M logins worth.
• Hard timeout: 500ms — AI never blocks a login longer than this.

8. Safety Checks

Adaptive MFA output is subject to ai-gateway's standard pipeline:

• Input moderation: N/A (features are not user-content; system-crafted).
• Output validation: Schema-validated (risk_score, reasons, confidence); malformed output → fallback to rules.
• No PII in output: Gateway enforces that only structured risk decisions come back, not free text.

9. Versioning

Classifier version recorded on every decision. Rolling out a new version:

1. Deploy new classifier in shadow mode (runs in parallel; decisions not used).
2. Compare shadow output with production for ≥ 2 weeks.
3. Promote new classifier; old remains available for rollback for 30 days.
4. Record version transition in audit log.

10. Eval Loop

Quarterly eval:

• True positive rate: Of challenges triggered, how many turned out to be genuine attacks?
• False positive rate: Of challenges triggered, how many were user-verified legit?
• Missed attacks: Of known attacks (from downstream analytics), how many passed without challenge?
• User friction metric: Challenge rate over time; rising rate without rising attack rate = over-trigger.

Eval results feed classifier tuning and threshold calibration.

11. Why This Design

• Defense in depth: Rule-based baseline is the load-bearing mechanism; AI is a force multiplier, never a single point of failure.
• Graceful degradation: ai-gateway outage does not affect login availability.
• Transparent provenance: Every decision traceable, disputable, and auditable.
• Privacy-preserving: Features redacted before leaving the service boundary.