Microsoft Entra ID Integration Guide

This guide provides comprehensive instructions for integrating PKIaaS with Microsoft Entra ID (formerly Azure Active Directory) for enterprise user management and certificate provisioning.

Overview

The Entra ID integration provides: - User Synchronization - Automatic user provisioning from Entra ID - Group-based Role Mapping - Automatic role assignment based on security groups - Certificate Provisioning - Automated certificate issuance for Entra ID users - JWT Token Validation - Bearer token authentication support - Device Integration - Support for device-bound certificates

Prerequisites

Entra ID Requirements

  • Entra ID Tenant - Premium P1 or P2 subscription recommended
  • Application Registration - App registration with appropriate permissions
  • Security Groups - Configured groups for role mapping
  • Certificate Policies - Defined certificate policies for users

PKIaaS Requirements

  • PKIaaS v1.0+ - With Entra ID integration support
  • External Database - MariaDB or MySQL for production
  • Redis Cache - For token and session caching
  • HTTPS - Required for secure token exchange

Configuration Steps

1. Entra ID Application Registration

Create Application Registration

  1. Navigate to Azure Portal → Entra ID → App registrations
  2. Click New registration
  3. Configure application:
  4. Name: PKIaaS Integration
  5. Supported account types: Accounts in this organizational directory only
  6. Redirect URI: Not required for daemon application

Configure API Permissions

Add the following Microsoft Graph permissions:

Application Permissions (Daemon):

User.Read.All          # Read user profiles
Group.Read.All         # Read security groups
Organization.Read.All  # Read organization information
Directory.Read.All     # Read directory objects

Delegated Permissions (Optional):

User.Read             # Read signed-in user profile
profile               # View basic profile
openid                # Sign users in

Generate Client Secret

  1. Navigate to Certificates & secrets
  2. Click New client secret
  3. Configure secret:
  4. Description: PKIaaS Integration Secret
  5. Expires: 24 months (recommended)
  6. Copy the secret value - You won't be able to see it again

Note Application Details

Record the following values from the Overview page: - Application (client) ID - Directory (tenant) ID - Client Secret (from previous step)

2. PKIaaS Configuration

Environment Configuration

Update .env file with Entra ID settings:

# Microsoft Entra ID (Azure AD) Integration
ENTRA_TENANT_ID=your-tenant-id-here
ENTRA_CLIENT_ID=your-client-id-here
ENTRA_CLIENT_SECRET=your-client-secret-here
ENTRA_AUTHORITY=https://login.microsoftonline.com/
ENTRA_GRAPH_URL=https://graph.microsoft.com/v1.0

# Certificate Configuration
ENTRA_DEFAULT_CERT_VALIDITY_DAYS=365
ENTRA_DEFAULT_KEY_SIZE=2048
ENTRA_ENABLE_AUTO_RENEWAL=true
ENTRA_ORGANIZATION_NAME="Your Organization"
ENTRA_COUNTRY_CODE=US
ENTRA_DEFAULT_DEPARTMENT=IT

# Authentication Settings
ENTRA_AUTO_CREATE_USERS=true
ENTRA_AUTO_ASSIGN_ROLES=true
ENTRA_SYNC_ON_LOGIN=true

# Security Settings
ENTRA_ENABLE_CERT_BINDING=true
ENTRA_STORE_OBJECT_IDS=true

Role Mapping Configuration

Configure role mapping in config/entra.php:

'role_mapping' => [
    // Entra ID Group Display Name => Application Role
    'PKI Administrators' => 'pki-admin',
    'Certificate Managers' => 'certificate-manager',
    'IT Security' => 'security-analyst',
    'Help Desk' => 'operator',
    'All Company' => 'user',

    // Department-specific roles
    'IT Department' => 'it-user',
    'HR Department' => 'hr-user',
    'Finance Department' => 'finance-user',
    'Engineering' => 'engineering-user',
],

Department Mapping

Configure department mapping for certificate subject generation:

'department_mapping' => [
    'IT Department' => 'Information Technology',
    'HR Department' => 'Human Resources',
    'Finance Department' => 'Finance',
    'Legal Department' => 'Legal',
    'Engineering' => 'Engineering',
    'Sales' => 'Sales',
    'Marketing' => 'Marketing',
],

3. Database Migration

Run database migrations to add Entra ID support:

# Run migrations
php artisan migrate

# Verify migration status
php artisan migrate:status

4. Test Connection

Test the Entra ID integration:

# Test Entra ID connectivity
php artisan entra:sync-users --dry-run

# Check health status
curl https://your-pkiaas-domain.com/api/v1/entra-id/health

User Synchronization

Automatic Synchronization

PKIaaS automatically synchronizes users on: - Daily Schedule - 4:00 AM daily sync via cron - Login Events - Real-time sync on authentication - API Requests - On-demand sync via API calls

Manual Synchronization

Sync Individual User

# Sync specific user by UPN
php artisan entra:sync-users --upn=john.doe@company.com

# Dry run to preview changes
php artisan entra:sync-users --upn=john.doe@company.com --dry-run

Bulk Synchronization

# Sync all users needing updates
php artisan entra:sync-users

# Force sync all users
php artisan entra:sync-users --all --force

# Batch processing with custom size
php artisan entra:sync-users --batch-size=25

API-based Synchronization

# Sync single user via API
curl -X POST https://your-pkiaas-domain.com/api/v1/entra-id/sync-user \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"user_principal_name": "john.doe@company.com"}'

# Bulk sync multiple users
curl -X POST https://your-pkiaas-domain.com/api/v1/entra-id/bulk-sync-users \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "user_principal_names": [
      "john.doe@company.com",
      "jane.smith@company.com"
    ]
  }'

Synchronization Process

The synchronization process:

  1. Authenticate - Obtain access token from Entra ID
  2. Fetch User Data - Retrieve user profile and group memberships
  3. Map Roles - Assign application roles based on security groups
  4. Update Database - Create or update user record
  5. Sync Metadata - Store groups, department, and sync timestamp

Certificate Provisioning

Automatic Provisioning

Configure automatic certificate provisioning for new users:

// In config/entra.php
'auto_provision_certificates' => true,
'default_certificate_types' => ['client_auth', 'email_protection'],
'provision_on_first_login' => true,

Manual Certificate Provisioning

Via API

# Provision certificate for Entra ID user
curl -X POST https://your-pkiaas-domain.com/api/v1/entra-id/provision-certificate \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": 123,
    "certificate_type": "client_auth",
    "validity_days": 365,
    "key_size": 2048
  }'

Via Command Line

# Provision certificate for user
php artisan entra:provision-certificate \
  --upn=john.doe@company.com \
  --type=client_auth \
  --validity=365

Certificate Profiles

Client Authentication Certificate

Subject: CN=John Doe, OU=IT Department, O=Your Organization, C=US
Subject Alternative Name:
  - email:john.doe@company.com
  - otherName:1.3.6.1.4.1.311.20.2.3;UTF8:john.doe@company.com (UPN)
Key Usage: Digital Signature, Key Agreement
Extended Key Usage: Client Authentication (1.3.6.1.5.5.7.3.2)
Certificate Policies: Your organization's client certificate policy OID

Email Protection Certificate

Subject: CN=John Doe, OU=IT Department, O=Your Organization, C=US
Subject Alternative Name:
  - email:john.doe@company.com
Key Usage: Digital Signature, Key Encipherment
Extended Key Usage: Email Protection (1.3.6.1.5.5.7.3.4)
Certificate Policies: Your organization's S/MIME certificate policy OID

Authentication Integration

JWT Token Validation

PKIaaS can validate Entra ID JWT tokens for authentication:

# Validate Entra ID token
curl -X POST https://your-pkiaas-domain.com/api/v1/entra-id/validate-token \
  -H "Content-Type: application/json" \
  -d '{
    "token": "eyJ0eXAiOiJKV1QiLCJhbGc..."
  }'

Bearer Token Authentication

Use Entra ID tokens for API authentication:

# Make authenticated API call with Entra ID token
curl -X GET https://your-pkiaas-domain.com/api/v1/certificates \
  -H "Authorization: Bearer ENTRA_ID_JWT_TOKEN"

Middleware Configuration

Configure Entra ID authentication middleware:

// In routes/api.php
Route::middleware(['entra-auth'])->group(function () {
    Route::get('/certificates', [CertificateController::class, 'index']);
    Route::post('/certificates', [CertificateController::class, 'store']);
});

Security Groups and Roles

Security Group Setup

Create security groups in Entra ID for role-based access:

Administrator Groups

  • PKI Administrators - Full system access
  • Certificate Managers - Certificate management
  • Security Analysts - Security monitoring and audit

User Groups

  • Certificate Users - Basic certificate operations
  • Department Groups - Department-specific access

Role Permissions

PKI Administrator

'permissions' => [
    'create-ca',
    'manage-certificates',
    'view-all-certificates',
    'revoke-certificates',
    'manage-users',
    'view-audit-logs',
    'manage-system-config'
]

Certificate Manager

'permissions' => [
    'create-certificates',
    'view-certificates',
    'renew-certificates',
    'revoke-own-certificates',
    'manage-certificate-requests'
]

Security Analyst

'permissions' => [
    'view-certificates',
    'view-audit-logs',
    'generate-reports',
    'monitor-security-events'
]

Monitoring and Troubleshooting

Health Monitoring

Health Check Endpoint

# Check Entra ID integration health
curl https://your-pkiaas-domain.com/api/v1/entra-id/health

Expected response:

{
  "success": true,
  "health": {
    "status": "healthy",
    "message": "Entra ID integration operational",
    "tenant_id": "your-tenant-id",
    "timestamp": "2024-01-15T10:30:00Z"
  }
}

Statistics Endpoint

# Get integration statistics
curl https://your-pkiaas-domain.com/api/v1/entra-id/statistics \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Common Issues and Solutions

Authentication Failures

Issue: 401 Unauthorized responses Causes: - Invalid client credentials - Expired client secret - Incorrect tenant ID - Missing API permissions

Solutions: 1. Verify client ID and secret in .env 2. Check token expiration and regenerate if needed 3. Confirm tenant ID in Azure portal 4. Grant admin consent for API permissions

User Synchronization Issues

Issue: Users not syncing from Entra ID Causes: - Network connectivity issues - Missing Graph API permissions - Rate limiting - User not found in directory

Solutions: 1. Test connectivity: php artisan entra:sync-users --dry-run 2. Check application permissions in Azure portal 3. Implement retry logic and backoff strategies 4. Verify user exists in Entra ID

Certificate Provisioning Failures

Issue: Certificate generation fails for Entra ID users Causes: - No suitable CA found - Invalid certificate profile - Missing user attributes - Department mapping issues

Solutions: 1. Configure CA selection strategy in config/entra.php 2. Validate certificate profiles and extensions 3. Check user profile completeness in Entra ID 4. Update department mapping configuration

Logging and Debugging

Enable Debug Logging

# In .env
LOG_LEVEL=debug
ENTRA_LOG_AUTH_ATTEMPTS=true
ENTRA_LOG_SYNC_EVENTS=true
ENTRA_LOG_CERTIFICATE_EVENTS=true

Log Analysis

Common log entries to monitor:

# Authentication events
grep "entra_authentication" storage/logs/laravel.log

# User synchronization
grep "user_sync" storage/logs/laravel.log

# Certificate provisioning
grep "certificate_provision" storage/logs/laravel.log

# API errors
grep "entra_api_error" storage/logs/laravel.log

Best Practices

Security Recommendations

  1. Rotate Client Secrets - Set 24-month expiration and rotate regularly
  2. Principle of Least Privilege - Grant minimal required API permissions
  3. Monitor Authentication - Enable comprehensive audit logging
  4. Secure Configuration - Store secrets in secure configuration management
  5. Regular Reviews - Audit group memberships and role assignments

Performance Optimization

  1. Token Caching - Cache access tokens for reuse
  2. Batch Processing - Use batch API calls for bulk operations
  3. Rate Limiting - Implement proper rate limiting and retry logic
  4. Database Indexing - Optimize queries with appropriate indexes
  5. Monitoring - Track API usage and performance metrics

Operational Procedures

  1. Regular Synchronization - Schedule daily user synchronization
  2. Certificate Lifecycle - Monitor certificate expiration and renewal
  3. Health Monitoring - Implement comprehensive health checks
  4. Backup Procedures - Regular backup of user mappings and certificates
  5. Incident Response - Document procedures for authentication failures

Migration Guide

From Traditional PKI

If migrating from a traditional PKI system:

  1. Export User Data - Export existing user certificates and mappings
  2. Create Entra ID Users - Ensure all users exist in Entra ID
  3. Configure Groups - Set up security groups for role mapping
  4. Migrate Certificates - Import existing certificates with user bindings
  5. Test Integration - Thoroughly test authentication and provisioning

From Other Identity Providers

When migrating from other identity providers:

  1. User Migration - Migrate users to Entra ID
  2. Group Mapping - Map existing groups to Entra ID security groups
  3. Certificate Re-issuance - Provision new certificates for migrated users
  4. Update Applications - Update client applications to use new endpoints
  5. Gradual Cutover - Implement phased migration approach

This comprehensive integration enables seamless enterprise user management and certificate provisioning through Microsoft Entra ID.

Vous n'avez pas envie de la manager ?

Découvrir notre offre PKI As A Service