README

A professional Drupal module providing seamless integration between Drupal and Microsoft Azure Active Directory through OpenID Connect, specifically customized for Howard University's authentication requirements.

Quick Start

Install the module:

composer require howard/howard_openid_connect_windows_aad
drush en howard_openid_connect_windows_aad

Configure Azure AD:
- Set up your Azure AD application (detailed guide)
- Configure redirect URIs and permissions
Configure Drupal:
- Visit /admin/config/services/openid-connect
- Select "Howard University Azure AD" as client
- Enter your Azure AD credentials
Test authentication:
- Visit /openid-connect/howard_windows_aad
- Complete the SSO flow

Features

🔐 Secure Authentication

Single Sign-On (SSO) with Azure Active Directory
OAuth2/OpenID Connect compliance
CSRF protection and secure token handling
HTTPS enforcement for all authentication flows

👥 User Management

Automatic user creation from Azure AD profiles
Profile synchronization with Azure AD data
Group-based role mapping from Azure AD to Drupal roles
Customizable user field mapping

🛠 Howard University Customizations

Specialized authentication flow for Howard University
Custom group mapping logic for Howard's organizational structure
Enhanced security measures for educational environments
Integration with Howard's existing systems

🎨 User Experience

Seamless login experience with Azure AD credentials
Automatic redirects to intended destinations
Clean user interfaces with hidden local password fields
Mobile-responsive authentication flows

⚙️ Administration

Comprehensive configuration options through Drupal admin UI
Detailed logging for authentication events and errors
Flexible role mapping configuration
Easy troubleshooting with built-in diagnostics

Architecture

This module extends Drupal's OpenID Connect ecosystem with:

Plugin-based architecture for easy extension
Event-driven processing for customization hooks
Service-oriented design with dependency injection
Configuration API integration for settings management
PSR-4 compliant autoloading and namespace organization

Documentation

Document	Description
Installation Guide	Complete setup instructions with Azure AD configuration
API Documentation	Technical API reference and integration details
Developer Guide	Development setup, testing, and contribution guidelines
Changelog	Version history and release notes
Coding Standards	Code quality and style guidelines
Release Checklist	Quality assurance and release procedures

Requirements

System Requirements

Drupal: 9.x or 10.x
PHP: 8.1 or higher
Database: MySQL 5.7+, PostgreSQL 10+, or MariaDB 10.3+
Web Server: Apache 2.4+ or Nginx 1.12+

Dependencies

OpenID Connect (^1.4 || ^2.0 || ^3.0)
Azure AD tenant with configured application
SSL/TLS certificate (required for production)

Installation

Via Composer (Recommended)

# Install the module
composer require howard/howard_openid_connect_windows_aad

# Enable the module
drush en howard_openid_connect_windows_aad

# Clear cache
drush cr

Manual Installation

Download the latest release from the repository
Extract to modules/contrib/howard_openid_connect_windows_aad
Enable via Drupal admin interface or Drush

For detailed installation instructions, see the Installation Guide.

Configuration

Basic Setup

Navigate to OpenID Connect settings:

Administration » Configuration » Web Services » OpenID Connect

Select Howard University Azure AD client:
- Check "Howard University Azure AD"
- Configure client credentials from Azure AD
Configure role mapping:
- Map Azure AD groups to Drupal roles
- Set default roles for new users
Test the configuration:
- Use the built-in test functionality
- Verify user creation and role assignment

Advanced Configuration

Custom field mapping for user profiles
Group-based access control configuration
Logging and monitoring setup
Performance optimization settings

See the Installation Guide for comprehensive configuration details.

Security

This module implements enterprise-grade security measures:

✅ OAuth2/OpenID Connect standard compliance
✅ HTTPS enforcement for all authentication flows
✅ CSRF protection using state parameters
✅ Token validation and secure storage
✅ Input sanitization and output encoding
✅ Session security with proper handling
✅ Regular security audits and updates

For detailed security information, see the Installation Guide.

Support

Getting Help

Documentation: Check the docs directory for comprehensive guides
Issues: Report bugs and feature requests through the project repository
Community: Join Howard University's developer community discussions

Professional Support

For enterprise support and custom development:

Contact Howard University IT Services
Professional consulting available through approved vendors

Contributing

We welcome contributions! Please see our Developer Guide for:

Development environment setup
Coding standards and guidelines
Testing requirements
Submission process

Quick Contribution Guide

Fork the repository
Create a feature branch
Make your changes following our coding standards
Add/update tests as needed
Update documentation
Submit a pull request

Testing

# Run unit tests
./vendor/bin/phpunit

# Check coding standards
./vendor/bin/phpcs --standard=Drupal,DrupalPractice src/

# Static analysis
./vendor/bin/phpstan analyse src/

See the Developer Guide for comprehensive testing information.

Changelog

See CHANGELOG.md for detailed version history and release notes.

License

This project is licensed under the GNU General Public License v2.0 or later - see the LICENSE file for details.

Credits

Development Team

Howard University IT Services - Primary development and maintenance
idfive - Component library and theming support

Based On

OpenID Connect Microsoft Azure Active Directory client - Original foundation module
OpenID Connect - Core OpenID Connect functionality

Special Thanks

Drupal community for the robust OpenID Connect ecosystem
Microsoft for comprehensive Azure AD documentation
All contributors and beta testers

Howard University | Information Technology Services
Empowering education through innovative technology solutions

howard / howard_openid_connect_windows_aad

Maintainers

Details