Shield: Authentication & Administration Service

:::info readme This document specifies the system requirements for Sparki Shield, the authentication and administrative service providing user management, SSO integration, workspace administration, RBAC, and internal operational tooling for the Sparki CI/CD platform. Shield is the identity layer that enables secure, compliant, and team-friendly authentication across all Sparki services. ::: :::success takeaways Key takeaways of this document include:

Understanding Shield’s authentication architecture and SSO capabilities
Recognizing workspace and team administration features
Identifying RBAC patterns and permission enforcement
Establishing security and compliance standards
Building scalable user management infrastructure
Enabling seamless enterprise SSO integration

::: Version: 1.0
Date: December 3, 2025
Repository: sparki-shield
Service Type: Authentication & Admin (Django + PostgreSQL)

1. Introduction

1.1 Purpose

This document specifies the system requirements for Sparki Shield, the authentication and administrative service. Shield provides user account lifecycle management, OAuth 2.0 and SAML 2.0 authentication, JWT token issuance and validation, workspace administration, role-based access control (RBAC), and internal operational dashboards.

1.2 Scope

Sparki Shield is a Django-based service that provides:

User account lifecycle management (registration, password management, profile)
OAuth 2.0 and SAML 2.0 authentication and SSO
JWT token issuance, validation, and refresh token management
Workspace and organization administration
Team member management and invitations
Role-based access control (RBAC) with fine-grained permissions
Permission caching for sub-millisecond authorization
Internal admin dashboard for platform management
Audit logging and compliance reporting
User activity tracking and analytics

1.3 Definitions

Property	Value
User	Individual with Sparki account credentials
Workspace	Team’s organizational container
Role	Set of permissions (owner, admin, developer, viewer)
SSO	Single Sign-On via OAuth 2.0/SAML 2.0
JWT	JSON Web Token for stateless authentication
Refresh Token	Long-lived token for obtaining new access tokens
Permission	Fine-grained authorization right
Audit Log	Immutable record of authentication events

1.4 Document Conventions

SHALL: Mandatory requirement
SHOULD: Recommended requirement
MAY: Optional requirement
WILL: External dependency or future intention

2. System Overview

2.1 System Context

Sparki Shield serves as the identity and access management (IAM) layer for the platform with integrated workspace collaboration and comprehensive operational standardization. It:

Authentication Gateway: Central authentication point for all Sparki services
Token Management: Issues and validates JWT tokens with Redis-based caching
User Lifecycle: Manages account creation, password management, and account deletion
Workspace Administration: Enables team management and organizational structure
SSO Integration: Supports enterprise SSO via OAuth 2.0, SAML 2.0, and identity providers
Permission Caching: Redis-based permission cache for <1ms authorization validation
Audit Logging: Comprehensive logging for compliance and security investigation
Admin Interface: Operations dashboard for platform administration
Event Publishing: Publishes authentication/authorization events for cross-service sync
Observability: Structured logging, Prometheus metrics, distributed tracing integration

2.2 System Objectives

Authentication Excellence: Industry-standard OAuth 2.0/SAML 2.0 with seamless UX
Ultra-Fast Validation: Sub-1ms token and permission validation via caching
Enterprise Scale: Support 1M+ users with sub-millisecond permission checks
High Availability: 99.95% uptime for authentication operations
Compliance: SOC 2, GDPR, HIPAA compliance with audit trails
Zero-Trust Architecture: Validate every request regardless of source
Developer Friendly: Simple API for authentication integration
Team Collaboration: Seamless workspace and team management
Security First: Industry-leading authentication practices
Operational Excellence: Comprehensive observability and alerting

3. Functional Requirements

3.1 User Management

REQ-SHIELD-USER-001: User Registration

Property	Value
ID	`REQ-SHIELD-USER-001`
Requirement	Shield SHALL support user registration with email verification via the `POST /auth/register` endpoint.
Rationale	Email verification prevents spam accounts and confirms user owns email address. Essential security practice.
Inputs	`{email, password, name}`
Outputs	User object and verification email sent
Verify Method	Test
Acceptance Criteria:	Password must meet complexity (8+ chars, uppercase, number, symbol) Returns 201 with user object (password excluded) Sends verification email with 24-hour token Account disabled until email verified Returns 409 if email already exists

REQ-SHIELD-USER-002: Email Verification

Property	Value
ID	`REQ-SHIELD-USER-002`
Requirement	Shield SHALL verify user email addresses through `GET /auth/verify/{token}`.
Rationale	Confirmed email enables password recovery and prevents account impersonation.
Inputs	Verification token from email
Outputs	Success page or error message
Verify Method	Test
Acceptance Criteria:	Activates account on valid token Returns 404 for invalid/expired token Tokens expire after 24 hours One-time use tokens (deleted after verification) Redirects to login after success

REQ-SHIELD-USER-003: Password Management

Property	Value
ID	`REQ-SHIELD-USER-003`
Requirement	Shield SHALL support password reset and change flows through `POST /auth/password-reset` and `POST /auth/password-change`.
Rationale	Users forget passwords or need to change them for security. Secure password flows maintain account security while enabling access.
Inputs	Email for reset request, old_password + new_password for change
Outputs	Password reset email or success response
Verify Method	Test
Acceptance Criteria:	Reset request always returns 200 (prevents email enumeration) Reset tokens expire after 1 hour Tokens one-time use only New password must meet complexity requirements Invalidates all existing sessions on password change

REQ-SHIELD-USER-004: Profile Management

Property	Value
ID	`REQ-SHIELD-USER-004`
Requirement	Shield SHALL support user profile updates through `PATCH /api/users/{id}/profile`.
Rationale	Users need to update profile information without changing credentials.
Inputs	User ID, partial profile data (name, avatar, timezone, language)
Outputs	Updated user object
Verify Method	Test
Acceptance Criteria:	User can only update own profile (or admin) Supports: name, avatar_url, timezone, language, notification_preferences Returns 403 if accessing other user’s profile Validates avatar URL is HTTPS

REQ-SHIELD-USER-005: Account Deletion

Property	Value
ID	`REQ-SHIELD-USER-005`
Requirement	Shield SHALL support account deletion through `DELETE /api/users/{id}` with confirmation requirements.
Rationale	GDPR and data privacy regulations require ability to delete personal account data. Confirmation prevents accidental deletion.
Inputs	User ID, password confirmation
Outputs	204 No Content on success or error response
Verify Method	Test
Acceptance Criteria:	Require password confirmation for security 30-day grace period before permanent deletion Notify user of pending deletion Support deletion cancellation within grace period Permanently delete PII after grace period

3.2 Authentication & Authorization

REQ-SHIELD-AUTH-001: OAuth 2.0 Authentication

Property	Value
ID	`REQ-SHIELD-AUTH-001`
Requirement	Shield SHALL support OAuth 2.0 authentication (Authorization Code flow) with Google, GitHub, and GitLab identity providers.
Rationale	OAuth 2.0 enables seamless social login, reducing signup friction and leveraging existing developer identities.
Inputs	OAuth provider (google, github, gitlab), authorization code
Outputs	Access token, refresh token, user information
Verify Method	Test + Demonstration
Acceptance Criteria:	Support Google OAuth 2.0 (Authorization Code flow) Support GitHub OAuth 2.0 (Authorization Code flow) Support GitLab OAuth 2.0 (Authorization Code flow) Handle OAuth callback securely Link OAuth account to existing user

OAuth Flow:

1. Redirect to OAuth provider (/oauth/authorize)
   ↓
2. User logs in to provider
   ↓
3. Provider redirects back with authorization code
   ↓
4. Exchange code for access token
   ↓
5. Fetch user info from provider
   ↓
6. Create/link Sparki user account
   ↓
7. Issue Sparki JWT tokens
   ↓
8. Redirect to dashboard

REQ-SHIELD-AUTH-002: SAML 2.0 SSO

Property	Value
ID	`REQ-SHIELD-AUTH-002`
Requirement	Shield SHALL support SAML 2.0 Single Sign-On for enterprise identity providers (Okta, Azure AD, Google Workspace).
Rationale	SAML 2.0 enables enterprise SSO integration, essential for large organizations with centralized identity management.
Inputs	SAML 2.0 response from identity provider
Outputs	Access token, refresh token, user information
Verify Method	Test + Demonstration
Acceptance Criteria:	Support SAML 2.0 authentication Validate SAML signatures Support attribute mapping (email, name, groups) Handle SAML metadata Support JIT user provisioning from SAML

Supported Identity Providers:

Okta:
  - SAML 2.0 authentication
  - Group-based RBAC mapping
  - Just-in-time user provisioning

Azure AD:
  - SAML 2.0 or OpenID Connect
  - Conditional access support
  - Microsoft 365 integration

Google Workspace:
  - SAML 2.0 or OpenID Connect
  - Custom user attributes
  - Directory integration

REQ-SHIELD-AUTH-003: JWT Token Management

Property	Value
ID	`REQ-SHIELD-AUTH-003`
Requirement	Shield SHALL issue, validate, and manage JWT tokens with configurable expiration and refresh token rotation.
Rationale	JWT tokens enable stateless authentication across all Sparki services without session storage overhead.
Inputs	User credentials or refresh token
Outputs	Access token (short-lived), refresh token (long-lived), token type
Verify Method	Test
Acceptance Criteria:	Access tokens expire after 1 hour Refresh tokens expire after 30 days Support token refresh via refresh token Validate JWT signatures on every request Revoke tokens on logout

JWT Payload:

{
    "sub": "user_123",
    "email": "alice@example.com",
    "workspace_id": "ws_456",
    "roles": ["owner"],
    "permissions": ["read:deployments", "write:pipelines"],
    "iat": 1702648245,
    "exp": 1702651845,
    "iss": "sparki-shield",
    "aud": "sparki-platform"
}

REQ-SHIELD-AUTH-004: Multi-Factor Authentication (MFA)

Property	Value
ID	`REQ-SHIELD-AUTH-004`
Requirement	Shield SHOULD support optional MFA via TOTP (Time-based One-Time Password) for enhanced security.
Rationale	MFA provides defense against credential compromise, essential for privileged accounts.
Inputs	User credentials, MFA code
Outputs	Access token if MFA verification succeeds
Verify Method	Test + Demonstration
Acceptance Criteria:	Support TOTP-based MFA (Google Authenticator, Authy) Allow users to enable/disable MFA Provide backup codes for account recovery Enforce MFA for admin accounts

3.3 Workspace & Team Management

REQ-SHIELD-WORKSPACE-001: Workspace Creation & Management

Property	Value
ID	`REQ-SHIELD-WORKSPACE-001`
Requirement	Shield SHALL support workspace creation, configuration, and lifecycle management via `/api/workspaces` endpoints.
Rationale	Workspaces provide organizational boundaries for teams and their CI/CD workflows.
Inputs	Workspace name, description, settings
Outputs	Workspace object with generated workspace ID
Verify Method	Test
Acceptance Criteria:	Create workspaces with unique names per user Support workspace renaming and settings updates List user’s workspaces Support workspace deletion (with data archival) Set workspace-level configuration

Workspace Model:

{
    "id": "ws_123456",
    "name": "acme-engineering",
    "slug": "acme-engineering",
    "description": "Acme Engineering Team",
    "owner_id": "user_123",
    "created_at": "2025-01-01T00:00:00Z",
    "updated_at": "2025-12-03T10:30:00Z",
    "settings": {
        "default_branch": "main",
        "require_approval": true,
        "auto_scale": true
    }
}

REQ-SHIELD-WORKSPACE-002: Team Member Management

Property	Value
ID	`REQ-SHIELD-WORKSPACE-002`
Requirement	Shield SHALL support team member management (invitations, roles, removals) via `/api/workspaces/{id}/members`.
Rationale	Team member management enables collaborative CI/CD workflows within workspaces.
Inputs	User email, role, invitation expiration
Outputs	Workspace member object or invitation token
Verify Method	Test + Demonstration
Acceptance Criteria:	Send email invitations to add members Assign roles on invitation acceptance Remove members from workspace Update member roles Track member activity and last login

REQ-SHIELD-WORKSPACE-003: Role-Based Access Control (RBAC)

Property	Value
ID	`REQ-SHIELD-WORKSPACE-003`
Requirement	Shield SHALL implement comprehensive RBAC with predefined roles (owner, admin, developer, viewer) and fine-grained permissions.
Rationale	RBAC enables secure delegation of responsibilities while maintaining control over sensitive operations.
Inputs	User, role, resource context
Outputs	Access decision (allow/deny) based on role and permissions
Verify Method	Test
Acceptance Criteria:	Define predefined roles (owner, admin, developer, viewer) Support custom roles with custom permissions Enforce permissions consistently Cache permissions for <1ms validation Log all access decisions

Predefined Roles:

Owner:
  - Full workspace control
  - Team member management
  - Billing and settings
  - Cannot be removed without transfer

Admin:
  - Pipeline and project management
  - User management (except billing)
  - Deployment approval
  - Cannot modify workspace settings

Developer:
  - Create and edit pipelines
  - Execute builds and deployments
  - View logs and metrics
  - Cannot approve production deployments

Viewer:
  - View-only access to pipelines
  - View build logs and status
  - Cannot execute any operations

Permission Matrix:

Permissions:
  read:workspace
  write:workspace_settings
  read:pipelines
  write:pipelines
  read:builds
  execute:builds
  read:deployments
  approve:deployments
  execute:deployments
  manage:members
  manage:roles
  read:audit_logs

3.4 Permission Caching & Authorization

REQ-SHIELD-CACHE-001: Redis Permission Cache

Property	Value
ID	`REQ-SHIELD-CACHE-001`
Requirement	Shield SHALL cache user permissions in Redis with automatic invalidation on permission changes for sub-1ms authorization.
Rationale	Permission caching enables real-time services to perform authorization checks in <1ms without database queries.
Inputs	User ID, workspace ID
Outputs	Cached permission set from Redis or database lookup
Verify Method	Test + Performance Testing
Acceptance Criteria:	Cache permissions with 15-minute TTL Return cached permissions in <1ms Invalidate cache on permission changes Support cache warming on startup Fall back to database on cache miss

Cache Key Format:

perm:{user_id}:{workspace_id} → {permission_list}
user:{user_id}:roles:{workspace_id} → {role_list}
user:{user_id}:workspaces → {workspace_ids}

REQ-SHIELD-CACHE-002: Authorization Service for Other Services

Property	Value
ID	`REQ-SHIELD-CACHE-002`
Requirement	Shield SHALL provide authorization service via `POST /auth/authorize` for other Sparki services to validate permissions.
Rationale	Distributed authorization enables every Sparki service to perform quick permission checks without direct database access.
Inputs	User ID/token, resource, action
Outputs	Authorization result (allow/deny) with cached permissions
Verify Method	Test + Performance Testing
Acceptance Criteria:	Return authorization decision in <5ms Support batch authorization checks Return cached permission list for client caching Support complex permission queries (AND/OR logic)

3.5 Audit Logging & Compliance

REQ-SHIELD-AUDIT-001: Authentication Event Logging

Property	Value
ID	`REQ-SHIELD-AUDIT-001`
Requirement	Shield SHALL log all authentication events (login, logout, SSO, MFA) with complete context for compliance and security.
Rationale	Authentication audit logging enables incident investigation and compliance verification.
Inputs	Authentication event (login, logout, SSO, MFA)
Outputs	Immutable audit log entry
Verify Method	Test
Acceptance Criteria:	Log all authentication events Include IP address and user agent Include success/failure status with reason Include timestamp with timezone Enable audit log queries

Audit Event Structure:

{
    "event_id": "audit_123456",
    "event_type": "user_login",
    "timestamp": "2025-12-03T10:30:45.123Z",
    "user_id": "user_123",
    "email": "alice@example.com",
    "status": "success",
    "method": "email_password",
    "ip_address": "203.0.113.42",
    "user_agent": "Mozilla/5.0...",
    "metadata": {
        "workspace_id": "ws_456",
        "mfa_required": true,
        "mfa_verified": true
    }
}

REQ-SHIELD-AUDIT-002: Authorization Event Logging

Property	Value
ID	`REQ-SHIELD-AUDIT-002`
Requirement	Shield SHALL log authorization decisions (access granted/denied) with decision rationale for audit trails.
Rationale	Authorization audit logging enables investigation of unauthorized access attempts and permission configuration errors.
Inputs	Authorization request (user, resource, action)
Outputs	Audit log entry with decision and rationale
Verify Method	Test
Acceptance Criteria:	Log authorization decisions on denied access Include decision rationale (missing permission, role not assigned) Sample successful access (1% sampling to reduce log volume) Enable authorization audit queries

4. Non-Functional Requirements

4.1 Performance Requirements

Requirement	Target	Measurement Method	Rationale
Login Response Time	<500ms	Auth latency tracking	Snappy authentication UX
Token Validation Latency	<5ms	Cache hit metrics	Real-time service authorization
Permission Cache Hit Rate	>95%	Cache metrics	Minimal database load
Password Hashing (bcrypt)	<200ms	Password hash timing	Balanced security/performance
SAML Assertion Processing	<100ms	SAML processing time	Enterprise SSO responsiveness

4.2 Scalability Requirements

Requirement	Target	Measurement Method	Rationale
Concurrent Users	1M+	Load testing	Global developer market scale
Concurrent Logins	10K+/sec	Load testing	Peak onboarding periods
Workspaces per User	100+	Database scaling	Power users with multiple orgs
Team Members per Workspace	10K+	Database scaling	Large enterprise teams

4.3 Reliability Requirements

Requirement	Target	Measurement Method	Rationale
Authentication Availability	99.95%	Uptime monitoring	Mission-critical service
Permission Cache Consistency	99.99%	Cache verification	Authorization accuracy
Audit Log Durability	99.999%	Storage durability	Compliance audit trail

4.4 Security Requirements

Requirement	Target	Measurement Method	Rationale
Password Hashing	bcrypt + salt	Code audit	Industry-standard protection
Token Encryption	TLS 1.3 + JWT	Security audit	Encrypted transmission and storage
Audit Log Tampering Prevention	Cryptographic	Hash verification	Compliance audit trail integrity
Rate Limiting on Auth	10/minute/IP	Traffic analysis	Brute force attack prevention

5. Integration Points

5.1 External Identity Providers

Google OAuth 2.0: https://accounts.google.com
GitHub OAuth 2.0: https://github.com/login/oauth
GitLab OAuth 2.0: https://gitlab.com/oauth
Okta SAML: https://{organization}.okta.com
Azure AD: https://login.microsoftonline.com

5.2 Cross-Service Integration

Shield → Sparki API (JWT validation)
Shield → Loco (Permission checks)
Shield → TUI (Token refresh)
Shield → PostgreSQL (User/workspace/role data)
Shield → Redis (Permission caching, session storage)
Shield → Email Service (Invitation/verification)

6. Success Metrics

Metric	Year 1 Target	Measurement Method
Login Success Rate	>99.5%	Authentication metrics
Token Validation Latency	<5ms	Performance tracking
Permission Cache Hit Rate	>95%	Cache metrics
SSO Adoption	70% of enterprise	Usage analytics
User Security Score	>8/10	Security audit

Document History:

Version	Date	Author	Changes
1.0	2025-12-03	Sparki Engineering	Initial Shield SRS creation

Getting Started

User Guides

Deployment & Operations

DevOps

API Reference

Architecture

Specifications

Forgery Advanced Specs

System Requirements Specs

UI Specifications

Monetization

Integration

Testing

Reports & Status

​Shield: Authentication & Administration Service

​1. Introduction

​1.1 Purpose

​1.2 Scope

​1.3 Definitions

​1.4 Document Conventions

​2. System Overview

​2.1 System Context

​2.2 System Objectives

​3. Functional Requirements

​3.1 User Management

​REQ-SHIELD-USER-001: User Registration

​REQ-SHIELD-USER-002: Email Verification

​REQ-SHIELD-USER-003: Password Management

​REQ-SHIELD-USER-004: Profile Management

​REQ-SHIELD-USER-005: Account Deletion

​3.2 Authentication & Authorization

​REQ-SHIELD-AUTH-001: OAuth 2.0 Authentication

​REQ-SHIELD-AUTH-002: SAML 2.0 SSO

​REQ-SHIELD-AUTH-003: JWT Token Management

​REQ-SHIELD-AUTH-004: Multi-Factor Authentication (MFA)

​3.3 Workspace & Team Management

​REQ-SHIELD-WORKSPACE-001: Workspace Creation & Management

​REQ-SHIELD-WORKSPACE-002: Team Member Management

​REQ-SHIELD-WORKSPACE-003: Role-Based Access Control (RBAC)

​3.4 Permission Caching & Authorization

​REQ-SHIELD-CACHE-001: Redis Permission Cache

​REQ-SHIELD-CACHE-002: Authorization Service for Other Services

​3.5 Audit Logging & Compliance

​REQ-SHIELD-AUDIT-001: Authentication Event Logging

​REQ-SHIELD-AUDIT-002: Authorization Event Logging

​4. Non-Functional Requirements

​4.1 Performance Requirements

​4.2 Scalability Requirements

​4.3 Reliability Requirements

​4.4 Security Requirements

​5. Integration Points

​5.1 External Identity Providers

​5.2 Cross-Service Integration

​6. Success Metrics