Technical Reference

Deep dive into the PIMActivation module architecture and implementation details.

🏗️ Architecture Overview

Module Structure

PIMActivation/
├── PIMActivation.psd1          # Module manifest
├── PIMActivation.psm1          # Root module
├── Public/                     # Exported functions
│   └── Start-PIMActivation.ps1
├── Private/                    # Internal functions
│   ├── Authentication/         # Auth handling
│   ├── RoleManagement/        # PIM role operations
│   ├── UI/                    # GUI components
│   ├── Utilities/             # Helper functions
│   └── Profiles/              # User profiles
└── docs/                      # Documentation

Key Components

Authentication Layer

• Connect-PIMServices: Establishes Microsoft Graph connection
• Get-AuthenticationContextToken: Handles authentication context challenges using WAM
• Clear-AuthenticationCache: Manages token cleanup

Role Management

• Get-PIMRoles: Retrieves eligible and active roles
• Invoke-PIMRoleActivation: Handles role activation logic
• Test-PIMRoleEligibility: Validates role eligibility

User Interface

• Initialize-PIMForm: Creates main window
• Show-PIMActivationDialog: Manages user interactions
• Update-PIMRolesList: Refreshes role displays

🔧 API Integration

Microsoft Graph API Endpoints

# Role eligibility schedules
GET https://graph.microsoft.com/v1.0/roleManagement/directory/roleEligibilitySchedules

# Role assignment schedules  
GET https://graph.microsoft.com/v1.0/roleManagement/directory/roleAssignmentSchedules

# Role activation
POST https://graph.microsoft.com/v1.0/roleManagement/directory/roleAssignmentScheduleRequests

Authentication Context Handling

# WAM-based token acquisition flow
1. Detect authentication context requirement
2. Load MSAL.NET assemblies from Az.Accounts module  
3. Use WAM broker for interactive authentication
4. Acquire context-specific token with claims
5. Cache token for reuse within session
6. Submit activation with context token via REST API

💾 Data Structures

Role Object Structure

@{
    Id = "schedule-id-guid"
    RoleDefinitionId = "role-definition-guid"
    RoleName = "Global Administrator"
    DirectoryScopeId = "/" # or specific scope
    Type = "Entra" | "Group" | "Azure"
    Status = "Eligible" | "Active"
    PolicyInfo = @{
        MaxDuration = 8
        RequiresMFA = $true
        RequiresJustification = $true
        RequiresTicket = $false
        RequiresApproval = $false
        AuthenticationContext = "c3"
    }
}

Configuration Storage

# User preferences location
$env:APPDATA\PIMActivation\preferences.json

# Structure
{
    "LastUsedAccount": "user@domain.com",
    "DefaultDuration": 4,
    "LastJustification": "Maintenance window",
    "WindowPosition": {
        "X": 100,
        "Y": 100
    }
}

🔐 Security Implementation

Token Management

• Tokens stored in-memory only
• Automatic cleanup on exit
• No persistent token storage
• Secure string handling for sensitive data

Permission Model

• Least privilege principle
• Uses WAM (Windows Web Account Manager) for secure authentication
• Only requested scopes:
  • RoleAssignmentSchedule.ReadWrite.Directory
  • RoleEligibilitySchedule.Read.Directory
  • User.Read
  • https://graph.microsoft.com/.default (for authentication context scenarios)

🐛 Error Handling

Error Categories

1. Authentication Errors

   • Token expiration
   • MFA challenges
   • Conditional Access blocks

2. API Errors

   • Rate limiting
   • Service unavailable
   • Invalid requests

3. Policy Violations

   • Missing justification
   • Duration exceeds maximum
   • Approval required

Error Recovery Strategy

try {
    # Primary operation
} catch [Microsoft.Graph.PowerShell.Models.ODataErrors.ODataError] {
    # Handle Graph API errors
} catch [System.Net.WebException] {
    # Handle network errors
} catch {
    # Generic error handling
}

📊 Performance Considerations

Optimization Techniques

• Parallel role enumeration for groups
• Cached policy information
• Batch API requests where possible
• Lazy loading of Azure resources

Memory Management

• Dispose of UI components properly
• Clear large collections after use
• Limit concurrent API calls

---

← Advanced Usage | Contributing →