Skip to content

Azure AD Deployment Checklist

Use this checklist to ensure all steps are completed for Azure AD deployment.

Pre-Deployment Checklist

Azure Portal Setup

  • [ ] Azure app registration created
  • [ ] Application (client) ID recorded
  • [ ] Directory (tenant) ID recorded
  • [ ] Client secret generated and saved securely
  • [ ] Client secret expiration date recorded (set calendar reminder)
  • [ ] Microsoft Graph User.Read permission added
  • [ ] Admin consent granted for permissions
  • [ ] Development redirect URI configured: http://localhost:5000/auth/callback
  • [ ] Production redirect URI configured: https://your-domain.com/auth/callback

Database Preparation

  • [ ] Production database backup created
  • [ ] Backup verified and downloadable
  • [ ] Migration file reviewed: migrations/versions/a1f2e3d4c5b6_add_azure_ad_support.py
  • [ ] Migration tested in development environment
  • [ ] Migration tested in staging environment (if available)

Code Review

  • [ ] All code changes reviewed and tested locally
  • [ ] Azure authentication tests passing (40+ tests)
  • [ ] Dev login working locally (DEV_AUTH_BYPASS=True)
  • [ ] Real Azure login tested locally (optional but recommended)
  • [ ] No secrets committed to git
  • [ ] instance/config.py added to .gitignore

Configuration Files

  • [ ] instance/config.py.example created with template
  • [ ] Production instance/config.py prepared (DO NOT COMMIT)
  • [ ] AZURE_AD_CLIENT_ID set correctly
  • [ ] AZURE_AD_CLIENT_SECRET set correctly
  • [ ] AZURE_AD_TENANT_ID set correctly
  • [ ] AZURE_AD_ENABLED set to True
  • [ ] DEV_AUTH_BYPASS set to False (CRITICAL)
  • [ ] DEFAULT_ROLE set to 'Pilot'

Dependencies

  • [ ] msal==1.26.0 added to requirements.txt
  • [ ] Requirements installed in development: pip install -r requirements.txt
  • [ ] Docker image rebuilt (if using Docker): docker-compose build web

User Communication

  • [ ] Users notified of upcoming authentication change
  • [ ] Email sent explaining new Microsoft login process
  • [ ] Help documentation updated
  • [ ] Support team briefed on new authentication

Deployment Day Checklist

Morning (Before Deployment)

  • [ ] Staging environment tested one final time
  • [ ] Emergency admin account verified (local password working)
  • [ ] Rollback procedure reviewed by team
  • [ ] Support team on standby
  • [ ] Database backup created (timestamp: _______)

Deployment Steps

  • [ ] Code deployed to production: git pull origin master
  • [ ] Dependencies installed/updated
  • [ ] Migration applied: flask db upgrade
  • [ ] Migration verified: flask db current shows a1f2e3d4c5b6
  • [ ] Configuration file uploaded to instance/config.py
  • [ ] File permissions set: chmod 600 instance/config.py
  • [ ] Web server restarted
  • [ ] Logs checked for startup errors: docker-compose logs web

Post-Deployment Verification

  • [ ] Azure AD enabled: Check config AZURE_AD_ENABLED=True
  • [ ] Dev bypass disabled: Check config DEV_AUTH_BYPASS=False
  • [ ] Dev login returns 403: Visit /auth/dev-login
  • [ ] Login redirects to Microsoft: Visit /login
  • [ ] New user can login and provision successfully
  • [ ] Existing user can login and auto-link successfully
  • [ ] Audit logs show azure_provision and azure_link events
  • [ ] Pending users visible in admin panel: /admin/users/pending-review
  • [ ] Password change blocked for Azure users
  • [ ] Logout redirects to Azure logout endpoint

Week 1 Monitoring Checklist

Daily Tasks

  • [ ] Day 1: Check audit logs for failed logins
  • [ ] Day 1: Verify all team members can login
  • [ ] Day 2: Check for email mismatch issues
  • [ ] Day 3: Review pending users in admin panel
  • [ ] Day 4: Manually link any mismatched accounts
  • [ ] Day 5: Review week 1 login statistics
  • [ ] Day 7: Team meeting - discuss any issues

Weekly Monitoring Queries

-- Failed logins (investigate if > 5)
SELECT COUNT(*) as failed_count
FROM audit_log
WHERE action = 'login'
AND message LIKE '%failed%'
AND timestamp > NOW() - INTERVAL 7 DAY;

-- New Azure users this week
SELECT u.email, u.created_date, u.auth_method, r.title
FROM user u
JOIN role r ON u.role_id = r.id
WHERE u.auth_method IN ('azure_ad', 'both')
AND u.created_date > NOW() - INTERVAL 7 DAY;

-- Users with both auth methods (auto-linked)
SELECT u.email, u.auth_method
FROM user u
WHERE u.auth_method = 'both';

Week 2 Role Review Checklist

Pending User Reviews

  • [ ] Visit admin panel: /admin/users/pending-review
  • [ ] Review each new user:
  • [ ] Verify user is Napier staff/student
  • [ ] Check if user should be Responsible Officer
  • [ ] Document promotion decisions
  • [ ] Promote appropriate users via edit page
  • [ ] Send welcome email to new users
  • [ ] Update internal user roster

Role Assignment Criteria

Pilot Role (Default): - Students taking drone courses - Researchers conducting flights - New staff members

Responsible Officer (Manual Promotion): - Full-time staff managing drone operations - Faculty leading research projects with multiple flights - Technical staff maintaining equipment

Emergency Rollback Checklist

If Azure AD Fails Completely

Option 1: Disable Azure (Quick - 5 minutes) - [ ] SSH to production server - [ ] Edit instance/config.py - [ ] Set AZURE_AD_ENABLED = False - [ ] Restart web server: docker-compose restart web - [ ] Verify legacy login works: /login - [ ] Notify users to use local passwords - [ ] Schedule Azure debugging session

Option 2: Enable Dev Bypass (EMERGENCY ONLY - 2 minutes) - [ ] Edit instance/config.py - [ ] Set DEV_AUTH_BYPASS = True - [ ] Restart web server - [ ] Admin uses /auth/dev-login to access system - [ ] FIX AZURE IMMEDIATELY - [ ] Disable dev bypass as soon as fixed

Option 3: Full Rollback (Complete - 30 minutes) - [ ] Set AZURE_AD_ENABLED = False - [ ] Rollback migration: flask db downgrade - [ ] Restore old routes_auth.py: git checkout HEAD~1 app/routes_auth.py - [ ] Restart web server - [ ] Verify legacy login works - [ ] Notify all users - [ ] Reset passwords for Azure-only users

Long-Term Maintenance Checklist

Monthly Tasks

  • [ ] Review audit logs for authentication anomalies
  • [ ] Check pending user count (should be low after week 2)
  • [ ] Verify client secret expiration date

Quarterly Tasks (Every 3 Months)

  • [ ] Review all user roles
  • [ ] Check for dormant Azure accounts
  • [ ] Test Azure login flow with new user
  • [ ] Update documentation if any changes made

Annual Tasks (Every 12 Months)

  • [ ] CRITICAL: Renew Azure client secret (2 months before expiry)
  • [ ] Review Azure AD permissions
  • [ ] Audit all Responsible Officer accounts
  • [ ] Test emergency rollback procedure
  • [ ] Update deployment documentation

Troubleshooting Checklist

Issue: Users Cannot Login

  • [ ] Check Azure service status: https://status.azure.com/
  • [ ] Verify AZURE_AD_ENABLED=True in config
  • [ ] Check redirect URI matches in Azure Portal
  • [ ] Review audit logs for error messages
  • [ ] Test with known working account (yours)
  • [ ] Check browser console for JavaScript errors
  • [ ] Verify session storage working (filesystem)

Issue: "Invalid State Token" Errors

  • [ ] Check session timeout (default: 5 minutes)
  • [ ] Verify flask_session/ directory exists
  • [ ] Check directory permissions (writable by web server)
  • [ ] Review session configuration in app/__init__.py
  • [ ] Test with different browser (check cookies enabled)
  • [ ] Find user in database with different email
  • [ ] Manually update user email to match Azure: 
    UPDATE user SET email = 'correct@napier.ac.uk' WHERE id = 123;
  • [ ] Ask user to login again
  • [ ] Verify auto-linking in audit logs

Issue: Client Secret Expired

  • [ ] Azure Portal > App registrations > Your App > Certificates & secrets
  • [ ] Generate new client secret
  • [ ] Update instance/config.py immediately
  • [ ] Restart web server
  • [ ] Verify login works
  • [ ] Delete old expired secret from Azure

Success Criteria

Deployment is considered successful when:

  • [ ] All users can login via Microsoft Azure AD
  • [ ] New users auto-provisioned with Pilot role
  • [ ] Existing users auto-linked by email match
  • [ ] Audit logs show successful azure_provision and azure_link events
  • [ ] No duplicate user accounts created
  • [ ] Admin panel shows pending users for review
  • [ ] Password change disabled for Azure-only users
  • [ ] Dev bypass is disabled (returns 403)
  • [ ] Zero downtime during deployment
  • [ ] No rollback needed in first 7 days
  • [ ] User satisfaction: < 5 support tickets in first week

Sign-Off

Deployment Team

Role Name Sign-Off Date
Developer
System Administrator
Project Manager
Database Administrator
Security Officer

Deployment Completed

  • Date: ______
  • Time: ______
  • Deployed By: ______
  • Verified By: ______

Notes

Use this space to document any issues, workarounds, or deviations from the plan:

Checklist Version: 1.0 Last Updated: 2026-02-19