Skip to content

Super Administrator Terminology Migration

Overview

This document tracks the transition from "System Administrator" to "Super Administrator" terminology in the Auth service. This change was implemented to avoid confusion between application-level administrators (Auth service) and infrastructure-level administrators (OS/server management).

Status: Phase 1 (Documentation) Complete
Last Updated: 2025-12-12

Rationale for Terminology Change

Problem Statement

The term "system admin" or "system administrator" is ambiguous in the context of the Auth service:

  • Infrastructure administrators manage servers, operating systems, Kubernetes, Docker containers, and deployment infrastructure
  • Application administrators manage the Auth service itself, including tenants, users, applications, and security settings

This ambiguity causes confusion in:

  • Security documentation and compliance materials (FedRAMP)
  • Communication between operations and security teams
  • Incident response procedures
  • Access control policies and procedures

Solution

Adopt "Super Administrator" terminology for application-level administrators:

  • Clear differentiation: "Super Administrator" is unmistakably an application-level role
  • Hierarchical clarity: "Super" conveys the highest privilege level within the Auth application
  • Industry standard: Commonly used in enterprise SaaS applications (e.g., Salesforce, Office 365)
  • FedRAMP aligned: Provides clear terminology for recommended secure configuration documentation

Migration Phases

Phase 1: Documentation Updates (Completed)

Completion Date: 2025-12-12
Status: ✅ Complete

Changes Implemented:

  1. Terminology Disambiguation Sections Added:
  2. packages/auth/docs/security/recommended-secure-configuration.md
  3. packages/auth/docs/authorization/super-admin-access.md (renamed from system-admin-access.md)

  4. packages/auth/docs/authorization/admin-roles.md

  5. Documentation Files Updated (147 occurrences across 15 files):

  6. FedRAMP Security Guide: recommended-secure-configuration.md
  7. Admin Roles Documentation: admin-roles.md, super-admin-access.md
  8. User Guides (7 files): tenant-admin-guide.md, sso-integration-guide.md, users-groups-admin-guide.md, license-management-guide.md, access-requests-guide.md, monitoring-guide.md, resources-tools-guide.md

  9. Technical Documentation (5 files): configuration.md, cors-policy.md, uploads-configuration.md, api/README.md, api/upload-and-payload-management.md

  10. File Renames:

  11. system-admin-access.md → super-admin-access.md

  12. All cross-references updated

  13. Legend Updates:

  14. SA-only → SUA-only (Super Administrator only)
  15. SA-or-scope → SUA-or-scope
  16. SA-or-tenant-admin → SUA-or-tenant-admin
  17. SA-bypass → SUA-bypass

Backward Compatibility:

  • All code references remain unchanged (100% backward compatible)
  • Legacy identifiers documented in disambiguation sections
  • No breaking changes to APIs or functionality

Phase 2: Code Migration (Future)

Status: 🔜 Planned
Target Date: TBD (after Phase 1 validation period)

Code Elements Requiring Updates

1. Role Constants and Identifiers

Current (Legacy):

ROLE_AUTH_SYSTEM_ADMIN;

Proposed:

ROLE_AUTH_SUPER_ADMIN;

Migration Strategy:

  • Create new constant ROLE_AUTH_SUPER_ADMIN
  • Keep ROLE_AUTH_SYSTEM_ADMIN as alias for backward compatibility
  • Update all internal code references to use new constant
  • Maintain both constants for at least 2 major versions
  • Deprecate old constant with clear migration guidance

Affected Files (estimated):

  • packages/auth/src/constants.ts or similar
  • All controller and service files checking this role
  • Database seed files
  • Test fixtures

2. Group Names

Current (Legacy):

systemAdmins

Proposed:

superAdmins

Migration Strategy:

  • Database migration to rename group (with rollback support)
  • Update configuration files (auth.defaults.systemAdminGroup)
  • Maintain backward compatibility by checking both names
  • Deprecation period: 2 major versions

Affected Components:

  • Database: user_groups table
  • Configuration: auth.defaults settings
  • Authorization middleware
  • Admin assignment logic
  • Audit log filters

Migration Script (pseudo-code):

-- Migration UP
UPDATE user_groups
SET name = 'superAdmins'
WHERE name = 'systemAdmins';

-- Migration DOWN (rollback)
UPDATE user_groups
SET name = 'systemAdmins'
WHERE name = 'superAdmins';

3. Service Methods and Authorization Checks

Current (Legacy):

UserInfoAuthorization.isSystemAdmin;
TenantAuthorizationService.isSystemAdmin({ userId });

Proposed:

UserInfoAuthorization.isSuperAdmin;
TenantAuthorizationService.isSuperAdmin({ userId });

Migration Strategy:

  • Create new methods with isSuperAdmin naming
  • Keep old methods as wrappers calling new methods
  • Add deprecation warnings to old methods
  • Update all internal references to use new methods
  • Remove old methods after 2 major versions

Affected Files:

  • packages/auth/src/keys.js (UserInfoAuthorization interface)
  • packages/auth/src/services/is-tenant-admin.service.ts
  • packages/auth/src/providers/auth-middleware.provider.ts
  • All controllers checking admin status (estimated 50+ files)

4. UI Component Labels and Strings

Current (Legacy):

  • "System Admin" in dropdown labels
  • "system admin" in help text
  • "System Administrator" in tooltips

Proposed:

  • "Super Admin" in dropdown labels
  • "super admin" in help text
  • "Super Administrator" in tooltips

Migration Strategy:

  • Update Angular component templates (.html files)
  • Update component TypeScript files (.ts)
  • Update translation/i18n files if applicable
  • Search and replace in all UI files

Affected Files (44 matches across 33 files):

  • packages/ng-auth/src/app/tenant-details/dialog/tenant-details-dialog.component.ts
  • packages/ng-auth/src/app/tenant-details/dialog/tenant-details-dialog.component.html
  • packages/ng-auth/src/app/user-groups/dialogs/upsert-dialog/upsert-dialog.component.ts
  • packages/ng-auth/src/app/user-dashboard/user-upsert-component/user-upsert-component.ts
  • packages/ng-auth/src/app/user-dashboard/user-dashboard.component.ts
  • packages/ng-auth/src/app/providers-ui/upsert-provider/upsert-provider.component.ts
  • packages/ng-auth/src/app/jobs/dashboard/jobs-dashboard.component.ts
  • ... and 26 more files

5. API Endpoint Paths and Parameters

Current (Legacy):

No API path changes required

Proposed:

No changes - API paths remain unchanged for backward compatibility

Rationale:

  • Changing API paths would be a breaking change
  • Current paths don't explicitly reference "system admin"
  • Internal logic can be updated without affecting external contracts

6. Configuration Files and Environment Variables

Current (Legacy):

auth: {
  defaults: {
    systemAdminGroup: 'systemAdmins';
  }
}

Proposed:

auth: {
  defaults: {
    superAdminGroup: 'superAdmins',  // New property
    systemAdminGroup: 'superAdmins'   // Deprecated, kept for compatibility
  }
}

Migration Strategy:

  • Add new configuration property superAdminGroup
  • Maintain systemAdminGroup for backward compatibility
  • Code checks superAdminGroup first, falls back to systemAdminGroup
  • Deprecate old property with warning in logs
  • Remove old property after 2 major versions

7. Test Files and Fixtures

Affected Areas:

  • Unit test descriptions and assertions
  • Integration test scenarios
  • Test fixture data (seed users, groups)
  • Mock data with "system admin" references

Migration Strategy:

  • Update test descriptions to use "super admin"
  • Update fixture data with new constant names
  • Maintain some tests for backward compatibility validation
  • Update test documentation

8. Audit Logs and Analytics

Considerations:

  • Historical audit logs contain "system admin" terminology
  • Analytics queries and dashboards reference old terms
  • Log aggregation and monitoring alerts

Migration Strategy:

  • Do NOT retroactively change historical audit logs
  • Update log message templates for future logs
  • Create aliases in analytics queries (check both terms)
  • Update monitoring alert messages
  • Document terminology change in audit trail

Migration Timeline (Proposed)

Phase 1: Documentation (Completed)

Duration: Completed
Deliverables:

  • ✅ All documentation updated with "Super Administrator" terminology
  • ✅ Disambiguation sections added
  • ✅ Legacy identifiers documented
  • ✅ Migration tracking document created

Phase 2: Code Preparation (Estimated: 2-4 weeks)

Activities:

  • Create new constants and methods
  • Add deprecation warnings to old code
  • Update internal references
  • Write database migration scripts
  • Create comprehensive test coverage

Deliverables:

  • New ROLE_AUTH_SUPER_ADMIN constant
  • New isSuperAdmin() methods
  • Database migration scripts (up/down)
  • Updated test suites

Phase 3: UI Updates (Estimated: 1-2 weeks)

Activities:

  • Update Angular component labels
  • Update help text and tooltips
  • Update error messages
  • Test all UI flows

Deliverables:

  • Updated UI components (33+ files)
  • Updated UI tests
  • UI regression testing complete

Phase 4: Rollout (Estimated: 2-4 weeks)

Activities:

  • Deploy to development environment
  • Validate all functionality
  • Deploy to staging with data migration
  • Monitor for issues
  • Deploy to production environments

Deliverables:

  • Successful deployment to all environments
  • Monitoring dashboards updated
  • No regression issues

Phase 5: Deprecation Period (Estimated: 6-12 months)

Activities:

  • Monitor usage of legacy identifiers
  • Log warnings for deprecated code paths
  • Provide migration guidance to API consumers
  • Plan removal of legacy code

Deliverables:

  • Usage metrics for legacy vs new identifiers
  • Migration completion rate tracked
  • Documentation for removing legacy code

Phase 6: Legacy Code Removal (Future Major Version)

Activities:

  • Remove deprecated constants and methods
  • Remove configuration aliases
  • Clean up code and reduce technical debt
  • Update major version

Deliverables:

  • Legacy code removed
  • Updated documentation (remove deprecation notices)
  • Major version release notes

Rollback Plan

If Issues Discovered During Phase 2+

Immediate Actions:

  1. Database migration rollback (revert group name)
  2. Revert code changes via Git
  3. Deploy previous version
  4. Restore configuration to previous state

Documentation:

  • Keep Phase 1 documentation changes (they remain accurate with legacy identifiers noted)
  • Update this migration document with lessons learned

Communication:

  • Notify all stakeholders of rollback
  • Document issues encountered
  • Plan remediation for next attempt

Testing Strategy

Phase 1 (Documentation) - Completed

Tests Performed:

  • ✅ Link validation (all markdown cross-references)
  • ✅ Grep verification (no unintended "system admin" references)
  • ✅ Documentation review (terminology consistency)
  • ✅ FedRAMP compliance review

Phase 2+ (Code Migration) - Future

Required Tests:

  1. Unit Tests:
  2. All authorization checks with new methods
  3. Configuration loading (both old and new properties)

  4. Database queries (both old and new group names)

  5. Integration Tests:

  6. Full admin flows (login, assign roles, perform admin actions)
  7. API endpoints requiring super admin access

  8. Group membership checks

  9. UI Tests:

  10. All UI components showing admin labels
  11. Help text and tooltips

  12. Error messages

  13. Migration Tests:

  14. Database migration up/down
  15. Data integrity validation

  16. Performance impact assessment

  17. Backward Compatibility Tests:

  18. Old constants still work
  19. Old methods still function
  20. Configuration backwards compatibility
  21. API clients using old terminology

Communication Plan

Internal Team

Before Phase 2:

  • Engineering team briefing on migration plan
  • Review of affected code and timeline
  • Assignment of tasks and responsibilities

During Phase 2:

  • Daily standup updates
  • Slack channel for migration questions
  • Weekly progress reports

After Phase 2:

  • Retrospective meeting
  • Documentation of lessons learned
  • Knowledge sharing session

External Stakeholders

Documentation:

  • Update public documentation with terminology
  • Release notes explaining change
  • Migration guide for API consumers (if needed)

Support Team:

  • Training on new terminology
  • FAQ for common questions
  • Support ticket templates updated

Customers:

  • No action required (documentation-only change in Phase 1)
  • Phase 2+ changes are backward compatible
  • Release notes provided with updates

Success Criteria

Phase 1 (Documentation)

  • ✅ All documentation uses "Super Administrator" terminology
  • ✅ Legacy identifiers clearly documented
  • ✅ No broken links or references
  • ✅ FedRAMP compliance maintained

Phase 2+ (Code Migration)

  • Zero security regressions
  • 100% backward compatibility maintained
  • All tests passing
  • No production incidents related to changes
  • Positive feedback from team
  • Clear deprecation path documented

Change Log

Date Phase Changes Author
2025-12-12 Phase 1 Documentation migration complete, tracking document created Auth Team

Questions and Feedback

For questions about this migration:

  • Create an issue in the auth-monorepo repository
  • Contact the Auth team via Slack
  • Email: [team email]