Admin Approval Process

API Version: 5.24.0

Overview

As an SSO Administrator, you control which users can access which applications in the DoneIsBetter ecosystem. This is a critical security responsibility that ensures only authorized users can access sensitive applications.

Your Responsibilities:

Review and approve/deny user access requests
Assign app-level roles (user vs admin)
Monitor active permissions across all apps
Revoke access when needed (security incidents, role changes)
Maintain audit trail of permission changes

Accessing the Admin Panel

Login

Navigate to https://sso.doneisbetter.com/admin
Enter your SSO admin email and 32-hex password token
Alternatively, request a magic link if configured
Session lasts 7 days with automatic extension

Admin Panel Layout

Users Tab - Manage user accounts and app permissions (primary focus)
OAuth Clients Tab - View registered applications
Settings - Admin account settings and logout

Approving User Access

When Users Need Approval

Users need approval in these scenarios:

First-time access - User tries to login to app for the first time
After revocation - User's access was previously revoked, they're requesting again
New app registration - App is newly registered, all users need approval

Step-by-Step Approval Process

1. Identify Pending Requests

Navigate to Admin Panel → Users tab:

Users List:
┌─────────────────────────────────────────────────┐
│ Name          │ Email              │ Actions   │
├─────────────────────────────────────────────────┤
│ John Doe      │ john@example.com   │ [View]    │ ← Click here
│ Jane Smith    │ jane@example.com   │ [View]    │
│ ...           │ ...                │ ...       │
└─────────────────────────────────────────────────┘

2. View User Details

Click "View" on a user to see their profile and app permissions:

User Details:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
User Information
  Name: John Doe
  Email: john@example.com
  ID: 550e8400-e29b-41d4-a716-446655440000

Application Access
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

┌─ Launchmass ────────────────────────┐
│ Landing page builder                │
│                                     │
│ Status: PENDING ⏳                  │ ← Needs approval!
│                                     │
│ Role: [Select ▼] [Grant Access]    │
└─────────────────────────────────────┘

┌─ Messmass ──────────────────────────┐
│ Messaging platform                  │
│                                     │
│ Status: APPROVED ✓                  │
│ Current Role: user                  │
│                                     │
│ Role: [user ▼] [Revoke Access]     │
└─────────────────────────────────────┘

3. Select Appropriate Role

Before granting access, choose the right role:

user (Default)
- Standard app access
- Cannot access admin features
- Best for: Regular users, team members
admin (Elevated)
- Full app access including admin panel
- Can manage app-specific users and settings
- Best for: Trusted administrators, app owners

4. Grant Access

Click the role dropdown next to "Grant Access"
Select "user" or "admin"
Click "Grant Access" button
Success message appears: "Access granted successfully"
Status changes to "APPROVED ✓"

5. Notify User (Optional)

SSO doesn't automatically email users. Consider:

Sending manual notification: "Your access to [App] has been approved"
Instructing user to try logging in again
Setting up Slack/Discord notifications for your team

Managing User Roles

Changing an Existing Role

If a user's responsibilities change:

Navigate to User Details → Application Access
Find app with status "APPROVED"
Click role dropdown (shows current role)
Select new role: "user" or "admin"
Change applies immediately

⚠️ Token Lag:
Role changes don't affect existing access tokens until they expire or refresh (max 1 hour). For immediate effect, consider revoking and re-granting access.

Common Role Change Scenarios

Promotion: user → admin
User is now managing app features, needs admin panel access
Demotion: admin → user
User no longer needs administrative privileges, reduce access

Revoking User Access

When to Revoke Access

User leaves organization - Offboarding process
Security incident - Compromised account
Policy violation - Terms of service breach
Role change - User no longer needs app access
Temporary suspension - Pending investigation

Revocation Process

Navigate to User Details → Application Access
Find app with status "APPROVED"
Click "Revoke Access" button
Confirm in dialog: "Are you sure you want to revoke access?"
Success message: "Access revoked successfully"
Status changes to "REVOKED ❌"

What Happens After Revocation

Immediate: User cannot complete new OAuth flows
Existing tokens: Remain valid until expiry (max 1 hour)
Next login attempt: Shows "Access Denied" message
Database record: Kept with status "revoked" (audit trail)
Re-approval: Can grant access again later if needed

🚨 Token Delay:
Revoked users can still use existing access tokens for up to 1 hour. For immediate lockout, contact app administrators to implement server-side session validation.

Batch Operations

Current Limitations

The admin panel currently requires one-by-one permission management. For bulk operations, contact development team to:

Build batch approval UI
Use API scripts for bulk grants/revokes
Export/import permission lists

API-Based Bulk Operations

For administrators comfortable with APIs:

// Bulk approve script example
const users = ['user-uuid-1', 'user-uuid-2', 'user-uuid-3'];
const clientId = 'launchmass-client-id';

for (const userId of users) {
  await fetch(`https://sso.doneisbetter.com/api/admin/app-permissions/${userId}`, {
    method: 'POST',
    credentials: 'include', // Admin session cookie
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      clientId: clientId,
      role: 'user',
      status: 'approved'
    })
  });
  console.log(`Approved ${userId}`);
}

Monitoring & Audit Trail

Permission Metadata

Every permission record includes audit fields:

createdAt - When permission was first requested (ISO 8601 UTC)
updatedAt - Last modification timestamp
grantedAt - When approval was granted
grantedBy - Admin user ID who granted access
revokedAt - When access was revoked (if applicable)
revokedBy - Admin user ID who revoked access

Viewing Audit Information

Currently, audit fields are stored in MongoDB but not shown in UI. To view:

Connect to MongoDB Atlas
Query appPermissions collection
Filter by userId or clientId
Examine audit fields

Future Audit Features

Planned enhancements:

Permission change history log in UI
Export audit reports (CSV/PDF)
Email notifications for permission changes
Slack/Discord integration for real-time alerts

Best Practices

Security

✅ Default to "user" role - Only grant "admin" when truly needed
✅ Review pending requests daily - Don't leave users waiting unnecessarily
✅ Verify user identity - Confirm via email/Slack before approving
✅ Document approval decisions - Keep notes on why access was granted
✅ Regular access reviews - Quarterly audit of who has what access
✅ Revoke on departure - Part of offboarding checklist
❌ Don't share admin credentials - Each admin should have own account

Workflow Efficiency

📋 Check pending requests daily - Morning routine
📋 Batch similar requests - Approve all "user" roles together
📋 Set approval criteria - Define who auto-qualifies (e.g., company email domain)
📋 Communicate expectations - Tell users typical approval time (e.g., "within 24 hours")
📋 Delegate when possible - Multiple SSO admins for coverage

Communication

💬 Notify users of approval - Manual email or Slack message
💬 Explain rejections - If denying, tell user why and next steps
💬 Announce new apps - When registering new app, notify team
💬 Coordinate with app admins - They manage org-level access, you manage SSO-level

Troubleshooting

User Says "Access Pending" But I Already Approved

Possible Causes:

User hasn't tried logging in again after approval
Wrong app - Check which app they're trying to access
Wrong user - Verify email matches SSO account
Cache issue - Have user clear browser cache/try incognito

Resolution:

Navigate to user details in admin panel
Verify status shows "APPROVED" for correct app
Have user logout and login again
Check browser console for OAuth errors

I Changed Role But User Still Has Old Permissions

Cause: Existing access tokens cached old role (max 1 hour)