AD Manager

A comprehensive Active Directory management tool built with ASP.NET Core, providing secure and efficient user management capabilities.

Recent Changes

Version 2.3.0 (2024-04-10)

Enhanced parent OU selection UI with improved dropdown design
Added validation for OU selection during object creation
Optimized LDAP queries for retrieving organizational units
Improved error handling when creating objects in selected OUs
Updated OpenTelemetry integration to version 1.11.2

Version 2.2.0 (2024-04-08)

Added parent OU selection capability for user, group, and OU creation modals
Added new dropdown to select target folder or OU when creating objects
Added GetAllOUs endpoint to retrieve all organizational units for dropdown population
Added JavaScript utilities for populating and displaying OU selection dropdowns
Modified user, group, and OU creation forms to include parent OU selection
Updated creation logic to respect the selected parent OU location
Improved user interface for object creation workflows

Version 2.0.0 (2024-03-26)

Added Office 365 integration for user and license management
Enhanced debug information display with Office 365 debug details
Added header size information in debug footer
Improved Office 365 service with detailed logging
Enhanced session tracking with additional configuration options

Version 1.2.0 (2024-03-26)

Updated version numbers across the application
Improved documentation consistency
Minor code optimizations

Version 1.1.0 (2024-03-25)

Added StorageManager ViewComponent for managing client-side storage
Implemented storage visualization UI to view localStorage items and sizes
Added storage cleanup functionality to clear non-essential storage items
Added size tracking for localStorage items
Added protection for essential items to preserve authentication, CSRF, and session data

Features

Active Directory user management
Secure authentication and authorization
Office 365 integration for user and license management
Rate limiting for sensitive endpoints
Comprehensive logging system
Enhanced security headers
Anti-forgery token protection
UPN suffix management
User password management
Audit logging
Session tracking and management
Debug information display
OpenTelemetry integration with Seq
Client storage management

Prerequisites

.NET 9.0 SDK or later
Active Directory domain access
SQLite (for logging)
Modern web browser

Installation

Clone the repository:

git clone [repository-url]
cd ADManager

Restore dependencies:

dotnet restore

Build the application:

dotnet build

Run the application:

dotnet run

Configuration

Copy the sample configuration file:

cp appsettings.sample.json appsettings.json

Edit appsettings.json and replace the demo values with your actual configuration:
- Update ActiveDirectory.Domain and ActiveDirectory.LdapPath with your domain information
- Configure Security settings according to your requirements
- Set up Seq server URL and API key if you're using Seq for logging
- Adjust other settings as needed

The application can be configured through appsettings.json. Key configuration sections include:

Active Directory Settings

"ActiveDirectory": {
  "Domain": "your-domain.com",
  "LdapPath": "LDAP://DC=your-domain,DC=com"
}

Security Settings

"Security": {
  "MaxFailedLoginAttempts": 3,
  "LockoutTimeInMinutes": 60,
  "PasswordPolicy": {
    "EnforceComplexity": true,
    "MinimumLength": 8,
    "RequiredCharacterClasses": 3
  },
  "AntiForgeryToken": {
    "TokenLifetimeInHours": 1,
    "RequireHashValidation": true,
    "SuppressXFrameOptionsHeader": false
  }
}

Debug Settings

"Debug": {
  "EnableDebugFooter": true,
  "ShowSessionId": true,
  "ShowAntiForgeryInfo": true,
  "ShowUserInfo": true,
  "ShowHostInfo": true
}

Logging Configuration

"Serilog": {
  "MinimumLevel": {
    "Default": "Information",
    "Override": {
      "Microsoft": "Warning",
      "System": "Warning",
      "ADManager.Middleware": "Debug"
    }
  },
  "Enrich": ["FromLogContext", "WithSessionId", "WithThreadId", "WithMachineName"],
  "Properties": {
    "Application": "ADManager"
  }
}

OpenTelemetry Configuration

"OpenTelemetry": {
  "ServiceName": "ADManager",
  "ServiceVersion": "2.2.0",
  "EnableConsoleExporter": true,
  "ActivitySources": [
    "ADManager",
    "ADManager.Middleware",
    "ADManager.Security"
  ],
  "SessionTracking": {
    "Enabled": true,
    "SessionIdHeader": "X-Session-ID",
    "SessionTimeoutMinutes": 30
  }
}

Office 365 Settings

"Office365": {
  "TenantId": "your-tenant-id",
  "ClientId": "your-client-id",
  "ClientSecret": "your-client-secret"
}

Security Features

Authentication

Form-based authentication
Windows Authentication support
Cookie-based session management
Account lockout protection
Password complexity requirements

Rate Limiting

Configurable request limits per endpoint
IP-based tracking
Customizable time windows
Proxy support

Security Headers

Content Security Policy
XSS Protection
Clickjacking Protection
MIME-type Sniffing Protection
Referrer Policy
Permissions Policy

Anti-Forgery Protection

Double validation system
Secure cookie storage
Audit logging
JavaScript integration

Session Tracking

Unique session ID generation
Configurable session timeout
Cross-request correlation
Integration with logging and telemetry

Logging System

Default Logging

SQLite-based logging (always enabled)
Location: {AppRoot}/logs.db
Table: Logs

Optional Logging Providers

Seq integration
OpenTelemetry support
Configurable log levels
Custom log paths

Telemetry Features

Activity source tracking
Request/response correlation
Cross-component tracing
Performance metrics collection
Exception and error recording

Debug Information

The application includes a configurable debug information footer that can display:

Current session ID
Anti-forgery token information
Authenticated user details
Host information
Application version

This can be enabled or disabled via the Debug configuration section in appsettings.json.

Development

Project Structure

ADManager/
├── Controllers/         # API and MVC controllers
├── Models/             # Data models and view models
├── Services/           # Business logic and services
├── Middleware/         # Custom middleware components
├── Filters/           # Action and exception filters
├── TagHelpers/        # Custom tag helpers for views
├── Logging/           # Logging extensions and enrichers
├── Attributes/        # Custom attributes
├── Data/              # Data access layer and context
├── Views/              # Razor views
├── wwwroot/           # Static files
└── Program.cs         # Application entry point

Building for Production

dotnet publish -c Release

Contributing

Fork the repository
Create a feature branch
Commit your changes
Push to the branch
Create a Pull Request

License

see LICENSE.md

Support

For support, please create an issue or contact the development team.

Logging Configuration

The application uses a flexible logging system with these components:

Default Logging (Always On)

SQLite Logging: All logs are saved to a SQLite database by default. This logging cannot be disabled and ensures that your application always maintains a log history.
- Default location: {AppRoot}/logs.db
- Table: Logs

Optional Logging

The following logging providers can be enabled or disabled via configuration in appsettings.json:

Seq Logging

Enable/disable by setting Seq:Enabled to true or false in appsettings.json
Configure the Seq server URL with Seq:ServerUrl
Configure the API key with Seq:ApiKey
Enable session tracking with Seq:SessionTracking:Enabled

OpenTelemetry

Enable/disable by setting OpenTelemetry:Enabled to true or false in appsettings.json
OpenTelemetry is configured to send data to Seq if Seq is also enabled
Configure service name with OpenTelemetry:ServiceName
Configure service version with OpenTelemetry:ServiceVersion
Configure activity sources with OpenTelemetry:ActivitySources
Configure session tracking with OpenTelemetry:SessionTracking

Configuration Example

{
  "Serilog": {
    "MinimumLevel": {
      "Default": "Information",
      "Override": {
        "Microsoft": "Warning",
        "System": "Warning",
        "ADManager.Middleware": "Debug"
      }
    },
    "Enrich": ["FromLogContext", "WithSessionId", "WithThreadId", "WithMachineName"],
    "Properties": {
      "Application": "ADManager"
    }
  },
  "OpenTelemetry": {
    "ServiceName": "ADManager",
    "ServiceVersion": "1.2.0",
    "EnableConsoleExporter": true,
    "ActivitySources": [
      "ADManager",
      "ADManager.Middleware",
      "ADManager.Security"
    ],
    "SessionTracking": {
      "Enabled": true,
      "SessionIdHeader": "X-Session-ID",
      "SessionTimeoutMinutes": 30
    }
  },
  "Seq": {
    "ServerUrl": "https://your-seq-server",
    "ApiKey": "your-api-key",
    "SessionTracking": {
      "Enabled": true,
      "SessionIdProperty": "SessionId",
      "SessionTimeoutMinutes": 30
    }
  }
}

Notes

For SQLite logging, you can use a relative path like logs.db which will save the logs in the application's root directory, or an absolute path like C:\Logs\admanager-logs.db
The application will automatically handle the path resolution, even if you specify a relative path

Rate Limiting Configuration

The application includes a rate limiting middleware to protect sensitive endpoints from brute force attacks and other abusive behavior.

Default Configuration

Protected Endpoints: The rate limiter targets authentication and password-related endpoints:
- /auth/login
- /resetpassword
- /changepassword
Default Limits: By default, the rate limiter allows 15 requests per minute for each client IP address per endpoint.

Configuration Options

Rate limiting is configured in the Program.cs file:

app.UseRateLimiting(maxRequests: 15, timeWindowSeconds: 60);

Parameters:

maxRequests: Maximum number of requests allowed within the time window (default: 15)
timeWindowSeconds: The time window in seconds for counting requests (default: 60)

How It Works

Each client is identified by their IP address
The middleware tracks requests for each client IP + endpoint combination
When a client exceeds the request limit for a specific endpoint, they receive a 429 (Too Many Requests) response
The response includes a "Retry-After" header indicating when they can retry

Advanced Configuration

To adjust rate limiting settings, modify the middleware configuration in Program.cs. Examples:

// More permissive: 30 requests per minute
app.UseRateLimiting(maxRequests: 30, timeWindowSeconds: 60);

// More restrictive: 5 requests per 2 minutes
app.UseRateLimiting(maxRequests: 5, timeWindowSeconds: 120);

Proxy Configuration

If your application is behind a proxy or load balancer, the middleware will use the X-Forwarded-For header to determine the client's IP address. Ensure your proxy is configured to set this header correctly.

Security Headers Configuration

The application implements security headers middleware to enhance web security by setting various HTTP headers that help protect against common web vulnerabilities.

Default Headers

The middleware automatically adds the following security headers to all responses:

Header	Value	Purpose
Content-Security-Policy-Report-Only	Complex policy	Controls resources the browser is allowed to load (report-only mode)
X-Content-Type-Options	nosniff	Prevents MIME-type sniffing
X-Frame-Options	SAMEORIGIN	Prevents clickjacking by forbidding embedding in frames from other origins
X-XSS-Protection	1; mode=block	Enables browser's XSS filtering
Referrer-Policy	strict-origin-when-cross-origin	Controls information in the Referer header
Permissions-Policy	Various restrictions	Restricts access to browser features

Content Security Policy

The application uses a Content Security Policy in report-only mode, which means violations are logged but not blocked. The policy includes:

default-src 'self';
script-src 'self' 'unsafe-inline' 'unsafe-eval' https://cdn.jsdelivr.net https://code.jquery.com https://*.microsoft.com;
style-src 'self' 'unsafe-inline' https://cdn.jsdelivr.net https://fonts.googleapis.com;
img-src 'self' data: https:;
font-src 'self' data: https://fonts.gstatic.com;
connect-src 'self' https:;
frame-ancestors 'self';
form-action 'self';
base-uri 'self';
object-src 'none'

Implementation

Security headers are enabled in Program.cs with:

app.UseSecurityHeaders(enableEnforcedCsp: false);

The enableEnforcedCsp parameter allows switching between enforcement mode and report-only mode for the Content Security Policy.

Session Tracking Configuration

The application includes a session tracking middleware that generates and maintains unique session IDs across requests, enabling better tracking and correlation of user activity.

Features

Unique Session ID Generation: Creates a cryptographically secure unique ID for each session
Cross-Request Correlation: Maintains the same session ID across multiple requests from the same client
Integration with Logging: Enriches logs with session IDs for easier debugging and audit trails
Integration with Telemetry: Adds session context to OpenTelemetry spans
Configurable Timeout: Session expiration can be configured in minutes

Configuration Options

Session tracking is configured in the appsettings.json file:

"OpenTelemetry": {
  "SessionTracking": {
    "Enabled": true,
    "SessionIdHeader": "X-Session-ID",
    "SessionTimeoutMinutes": 30
  }
}

Parameters:

Enabled: Whether session tracking is enabled (default: true)
SessionIdHeader: The HTTP header used to transmit the session ID (default: "X-Session-ID")
SessionTimeoutMinutes: The session timeout in minutes (default: 30)

Implementation

Session tracking is implemented in SessionTrackingMiddleware.cs and is enabled in Program.cs:

app.UseMiddleware<SessionTrackingMiddleware>();

Security Considerations

Session IDs are generated using a cryptographically secure random number generator
The middleware uses cookies with secure flags to store session information
Session IDs are not directly tied to authentication tokens, providing an additional layer of tracking

Anti-Forgery Token Configuration

The application implements enhanced anti-forgery token validation to protect against Cross-Site Request Forgery (CSRF) attacks. This protection goes beyond the default ASP.NET Core implementation with additional security layers.

Features

Double Validation: Validates tokens using both ASP.NET Core's built-in validation and a custom SHA-256 hash validation
Global Protection: Automatically protects all POST, PUT, DELETE, and PATCH requests
Secure Cookie Storage: Stores token hash in a secure, HTTP-only cookie with SameSite=Strict
Audit Logging: Records validation failures with user information and IP address
JavaScript Integration: Ensures all AJAX requests include anti-forgery tokens

Configuration Options

Anti-forgery token settings are configured in the Security:AntiForgeryToken section of appsettings.json:

"Security": {
  "AntiForgeryToken": {
    "TokenLifetimeInHours": 1,
    "RequireHashValidation": true,
    "SuppressXFrameOptionsHeader": false
  }
}

Setting	Description
TokenLifetimeInHours	How long tokens remain valid (default: 1 hour)
RequireHashValidation	Whether to perform the additional hash validation (default: true)
SuppressXFrameOptionsHeader	Whether to suppress the X-Frame-Options header (default: false)

Implementation

The enhanced anti-forgery validation is implemented using a custom middleware and is enabled in Program.cs:

// Add global anti-forgery validation
builder.Services.AddAntiforgery(options => {
    options.Cookie.Name = "X-CSRF-TOKEN";
    options.Cookie.HttpOnly = true;
    options.Cookie.SecurePolicy = CookieSecurePolicy.Always;
    options.Cookie.SameSite = SameSiteMode.Strict;
    options.HeaderName = "RequestVerificationToken";
    options.FormFieldName = "__RequestVerificationToken";
});

// In the pipeline configuration:
app.UseEnhancedAntiForgery();

Client-Side Integration

The application includes JavaScript that automatically adds anti-forgery tokens to all AJAX requests:

For JSON requests, the token is included in the "RequestVerificationToken" header
For form submissions, the token is included as a hidden form field
For FormData objects, the token is appended to the data
For URL-encoded data, the token is included as a parameter

Security Benefits

Protection Against CSRF: Prevents attackers from making unauthorized requests on behalf of authenticated users
Token Hash Validation: Makes it significantly harder to forge valid tokens, even if other security measures are compromised
Limited Token Lifetime: Reduces the window of opportunity for attacks if a token is somehow leaked
Transparent UX: Automatically handles token acquisition and validation without disrupting the user experience

Client Storage Management

The application includes a client storage management component that helps manage browser-based storage to keep cookies within RFC standards (under 4096 bytes) by using localStorage for non-sensitive data.

Features

Storage Visualization: Provides a UI to view all localStorage items and their sizes
Storage Cleanup: Allows users to clear non-essential storage items
Essential Item Protection: Preserves authentication, CSRF, and session-related items
Size Tracking: Displays the total size of all localStorage items

Implementation

The storage manager is implemented as a ViewComponent and can be included in any page with:

@await Component.InvokeAsync("StorageManager")

Security Considerations

The storage manager preserves authentication, CSRF token, and session-related data
Only client-side storage items are affected; server-side data remains intact
The component is designed for administrative use and should be included only in admin pages

Database Configuration

The application uses SQLite as its database engine. The database connection is configured in the ConnectionStrings section of appsettings.json:

"ConnectionStrings": {
  "DefaultConnection": "Data Source=|DataDirectory|\\admanager.db"
}

Connection String Options

The application supports the following formats for the connection string:

Using DataDirectory substitution:
```
"Data Source=|DataDirectory|\\admanager.db"
```
The |DataDirectory| token is replaced with the application's base directory at runtime.
Using relative path:
```
"Data Source=admanager.db"
```
The database file will be created in the application's working directory.
Using absolute path:
```
"Data Source=C:\\Path\\To\\admanager.db"
```
The database file will be created at the specified location.

Database Initialization

The application automatically creates the database if it doesn't exist. This process is handled during application startup in Program.cs. When the application starts, it:

Checks if the database exists
Creates the database if it doesn't exist
Creates all necessary tables based on the application's data models
Logs information about the database creation and tables

No additional setup or migration commands are required to initialize the database.

Office 365 Integration

The AD Manager now includes Office 365 integration capabilities, allowing you to manage users across both AD and Office 365 environments. This integration enables:

Viewing all Office 365 users
Blocking/unblocking user sign-ins
Managing user licenses
Configuring service plans
Synchronizing users between AD and Office 365

Setting up Microsoft Graph API Access

To enable Office 365 integration, you need to register an application in the Azure portal and grant it the necessary permissions to interact with Microsoft Graph API. Follow these steps:

1. Register an Application in Azure Active Directory

Sign in to the Azure Portal
Navigate to Azure Active Directory > App registrations
Click New registration
Enter a name for your application (e.g., "AD Manager")
For the Supported account types, select "Accounts in this organizational directory only"
Leave the Redirect URI blank (not needed for this application)
Click Register

2. Obtaining the Tenant ID and Client ID

After registering your application:

The Tenant ID is displayed in the Overview page as "Directory (tenant) ID"
The Client ID is displayed as "Application (client) ID"
Copy both values and save them for later

3. Creating a Client Secret

In your application's page, navigate to Certificates & secrets
Click New client secret
Add a description (e.g., "AD Manager Secret") and select an expiration period
Click Add
IMPORTANT: Copy the generated client secret value immediately and save it. This value is only shown once and cannot be retrieved later!

4. Assigning API Permissions

Your application needs appropriate permissions to manage Office 365 users and licenses:

In your application's page, navigate to API permissions
Click Add a permission
Select Microsoft Graph
Select Application permissions (not delegated permissions)
Add the following permissions:
- User.Read.All (Read all users' full profiles)
- User.ReadWrite.All (Read and write all users' full profiles)
- Directory.Read.All (Read directory data)
- Directory.ReadWrite.All (Read and write directory data)
- Organization.Read.All (Read organization information)
- UserAuthenticationMethod.ReadWrite.All (For blocking/unblocking sign-in)
- LicenseAssignment.ReadWrite.All (Manage license assignments)
Click Add permissions
Click Grant admin consent for [Your Organization] button at the top of the permissions page

5. Configuring AD Manager

Update your appsettings.json file with the values obtained above:

"Office365": {
  "TenantId": "your-tenant-id-from-step-2",
  "ClientId": "your-client-id-from-step-2",
  "ClientSecret": "your-client-secret-from-step-3" 
}

Restart the application to apply the changes

Security Considerations

The client secret allows administrative access to your Office 365 tenant. Keep it secure.
Consider using Azure Key Vault or another secrets management solution for production environments.
Regularly rotate the client secret (create a new one and update your configuration).
Use the minimum set of permissions required for your specific use case.
Implement proper audit logging for all Office 365 management actions.

Troubleshooting Office 365 Integration

If you encounter issues with the Office 365 integration:

Verify that all required permissions have been granted and admin consent provided.
Ensure your client secret hasn't expired.
Check network connectivity to the Microsoft Graph API endpoints.
Review application logs for detailed error messages.
Verify that the account used to grant consent has appropriate Office 365 administrator permissions.

Name		Name	Last commit message	Last commit date
Latest commit History 53 Commits
.github/workflows		.github/workflows
.vs/AD-Manager		.vs/AD-Manager
ADManager.Tests		ADManager.Tests
ADManager		ADManager
Tools		Tools
-i		-i
.gitignore		.gitignore
AD-Manager.sln		AD-Manager.sln
CHANGELOG.md		CHANGELOG.md
Directory.Build.props		Directory.Build.props
LICENSE.md		LICENSE.md
NOTICE.md		NOTICE.md
PROJECT_INDEX.md		PROJECT_INDEX.md
README.md		README.md
bump-version.bat		bump-version.bat
deploy.sample.ps1		deploy.sample.ps1
run.bat		run.bat

Folders and files

Latest commit

History

Repository files navigation

AD Manager

Recent Changes

Version 2.3.0 (2024-04-10)

Version 2.2.0 (2024-04-08)

Version 2.0.0 (2024-03-26)

Version 1.2.0 (2024-03-26)

Version 1.1.0 (2024-03-25)

Features

Prerequisites

Installation

Configuration

Active Directory Settings

Security Settings

Debug Settings

Logging Configuration

OpenTelemetry Configuration

Office 365 Settings

Security Features

Authentication

Rate Limiting

Security Headers

Anti-Forgery Protection

Session Tracking

Logging System

Default Logging

Optional Logging Providers

Telemetry Features

Debug Information

Development

Project Structure

Building for Production

Contributing

License

Support

Logging Configuration

Default Logging (Always On)

Optional Logging

Seq Logging

OpenTelemetry

Configuration Example

Notes

Rate Limiting Configuration

Default Configuration

Configuration Options

How It Works

Advanced Configuration

Proxy Configuration

Security Headers Configuration

Default Headers

Content Security Policy

Implementation

Session Tracking Configuration

Features

Configuration Options

Implementation

Security Considerations

Anti-Forgery Token Configuration

Features

Configuration Options

Implementation

Client-Side Integration

Security Benefits

Client Storage Management

Features

Implementation

Security Considerations

Database Configuration

Connection String Options

Database Initialization

Office 365 Integration

Setting up Microsoft Graph API Access

1. Register an Application in Azure Active Directory

2. Obtaining the Tenant ID and Client ID

3. Creating a Client Secret

4. Assigning API Permissions

5. Configuring AD Manager

Packages