Authentication & Authorization

Comprehensive security model for user authentication and resource authorization in Twig AI.

Authentication

Verify user identity through multiple methods.

Supported Methods

1. Email/Password

• Standard username/password

• Secure password hashing (bcrypt)

• Password requirements: 8+ characters, special chars

• Account lockout after failed attempts

2. Single Sign-On (SSO)

• SAML 2.0

• OAuth 2.0 / OpenID Connect

• Azure AD / Microsoft Entra

• Google Workspace

• Okta, OneLogin, custom IdPs

3. Multi-Factor Authentication (MFA)

• Time-based OTP (TOTP)

• SMS codes

• Authenticator apps

• Required for admin roles (recommended)

4. API Keys

• Programmatic access

• Bearer token authentication

• Scoped permissions

• Rotatable

Authorization

Control what authenticated users can do.

Role-Based Access Control (RBAC)

Four primary roles:

• Super Admin: Complete control

• Admin: Day-to-day management

• Manager: Team-level control

• User: Standard access

See User Permissions & Roles for complete matrix.

Resource-Level Permissions

Control access to specific resources:

Agents:

• View: Can see agent exists

• Use: Can query agent

• Edit: Can modify configuration

• Manage: Full control

Data Sources:

• View: Can see source

• Connect: Can add to agents

• Edit: Can modify settings

• Process: Can trigger sync

Groups:

• Member: Part of group

• Manager: Can add/remove members

• Admin: Full group control

Attribute-Based Access Control (ABAC)

Enterprise feature for fine-grained control:

{
  "policy": {
    "resource": "agent:agent-123",
    "action": "use",
    "conditions": [
      {"user.role": "manager"},
      {"user.department": "support"},
      {"time.hour": {">=": 9, "<=": 17}}
    ]
  }
}

Security Features

Session Management

Settings:

{
  "session": {
    "timeout": 28800,        // 8 hours
    "renewOnActivity": true,
    "maxConcurrent": 3,      // Max 3 sessions per user
    "enforceIPBinding": false
  }
}

Security Controls:

• Secure session cookies (httpOnly, secure, sameSite)

• Session invalidation on logout

• Automatic timeout after inactivity

• Concurrent session limits

Token Security

Access Tokens:

• Short-lived (1 hour default)

• JWT format with signature

• Includes user ID, org ID, roles

• Cannot be modified

Refresh Tokens:

• Long-lived (30 days)

• Securely stored

• Can be revoked

• Used to obtain new access tokens

Password Security

Requirements:

• Minimum 8 characters

• At least one uppercase letter

• At least one lowercase letter

• At least one number

• At least one special character

Storage:

• Bcrypt hashing (cost factor: 12)

• Salted per user

• Never stored in plain text

• Never logged

API Key Security

Generation:

• Cryptographically random

• Minimum 32 characters

• Prefix indicates type (sk_live_, sk_test_)

Storage:

• Hashed in database

• Only shown once at creation

• Cannot be retrieved later

Permissions:

• Scoped to specific operations

• Can be revoked instantly

• Audit log of all usage

Access Control Patterns

Least Privilege

Example:

Support Agent User:
✅ Can use support agents
✅ Can view their interactions
❌ Cannot create agents
❌ Cannot view all users
❌ Cannot access billing

Reasoning: Only what's needed for their job

Separation of Duties

Example:

Agent Creator:
✅ Can create and configure agents
❌ Cannot deploy to production

Production Approver:
❌ Cannot create agents
✅ Can deploy to production

Reasoning: Prevents unilateral changes

Time-Based Access

{
  "accessControl": {
    "allowedHours": {
      "start": 9,
      "end": 17,
      "timezone": "America/New_York"
    },
    "allowedDays": [1, 2, 3, 4, 5] // Mon-Fri
  }
}

Audit Logging

All authentication and authorization events are logged:

Logged Events:

• Login attempts (success/failure)

• Logout events

• Role changes

• Permission grants/revokes

• API key creation/deletion

• Resource access attempts

• Failed authorization attempts

Log Format:

{
  "timestamp": "2024-01-15T10:30:00Z",
  "event": "LOGIN_SUCCESS",
  "userId": "user-123",
  "email": "[email protected]",
  "ipAddress": "192.168.1.1",
  "userAgent": "Mozilla/5.0...",
  "mfaUsed": true,
  "sessionId": "session-456"
}

Retention: 90 days (configurable for Enterprise)

Security Best Practices

1. Enable MFA

✅ Require for admins ✅ Encourage for all users ✅ Use authenticator apps (more secure than SMS) ❌ Don't rely solely on passwords

2. Regular Access Reviews

✅ Quarterly user access reviews ✅ Remove inactive accounts ✅ Verify role assignments ✅ Audit API key usage ❌ Don't grant permanent access without review

3. Principle of Least Privilege

✅ Grant minimum necessary permissions ✅ Use groups for management ✅ Time-limit contractor access ❌ Don't make everyone admin

4. Monitor Failed Attempts

✅ Alert on repeated failures ✅ Automatic account lockout ✅ Investigate suspicious patterns ❌ Don't ignore security logs

Troubleshooting

Cannot Login

Check:

1. Correct email/password

2. Account is active

3. MFA code is correct

4. Not locked out

5. SSO is configured properly

Unauthorized API Requests

Check:

1. API key format correct

2. Key hasn't been revoked

3. Key has required scopes

4. Request to correct endpoint

5. Organization ID matches

Permission Denied

Check:

1. User has required role

2. Resource exists and user has access

3. Group memberships are correct

4. No time-based restrictions apply

Next Steps

• SSO Integration - Enterprise authentication

• Data Privacy - Data protection

• Security Best Practices - Harden security

• User Permissions - Manage roles