Okta Active Directory Integration

Synchronize on-premises Active Directory with Okta for modern authentication

As organizations migrate to cloud services, they often need to maintain existing Active Directory infrastructure while extending modern authentication capabilities to SaaS applications. Okta’s Active Directory Integration synchronizes identities between your on-premises AD and Okta, preserving established user management processes while enabling modern authentication features.

Prerequisites

• Okta Organization with Super Admin permissions
• Active Directory with Domain Admin or equivalent rights
• Network connectivity: Outbound HTTPS access from AD environment to Okta
• Email infrastructure: Users must have valid email addresses for activation

Step 1: Prepare Active Directory Environment

Create Dedicated Organizational Unit

# Create Dedicated OU
1. Open Active Directory Users and Computers
2. Right-click domain > New > Organizational Unit
3. Name the OU (e.g., "Okta Sync Users")
4. Move target users into this OU

Configure UPN Suffixes (If Required)

If your domain uses .local or non-email domains, add a routable UPN suffix:

# Add routable UPN suffix to forest
Get-ADForest | Set-ADForest -UPNSuffixes @{add="company.com"}

# Update user UPN suffixes
Get-ADUser -Filter * -SearchBase "OU=Okta Sync Users,DC=company,DC=local" | 
    Set-ADUser -UserPrincipalName {$_.SamAccountName + "@company.com"}

Verify User Email Addresses

# Check users without email addresses
Get-ADUser -Filter * -Properties mail -SearchBase "OU=Okta Sync Users,DC=company,DC=local" | 
    Where-Object {$_.mail -eq $null} | 
    Select-Object Name, SamAccountName, mail

Step 2: Install Okta AD Agent

Download and Prepare Agent

# Download Agent
1. Log into Okta Admin Console
2. Navigate to Directory > Directory Integrations
3. Click "Add Directory" and select "Active Directory"
4. Download the Okta AD Agent installer

Run Installation Wizard

# Installation Configuration
1. Execute installer with administrative privileges
2. Provide configuration details:
   - AD Domain: Select domain to synchronize
   - Service Account: Allow automatic creation or specify existing
   - Proxy Settings: Configure if required
   - Okta Organization URL: Your Okta tenant URL

# Complete Agent Activation
3. Copy activation code provided during installation
4. Follow activation link to complete setup
5. Verify agent status in Okta Admin Console

Step 3: Configure Directory Synchronization

Select Synchronization Scope

# Configure Synchronization Scope
Organizational Unit: Choose the OU containing target users

Username Format:
- UPN: If users have email-format UPNs
- Email: If using the mail attribute

Attribute Mapping Configuration

# Default Attribute Mappings
firstName: givenName
lastName: sn
email: mail or userPrincipalName
login: Based on selected username format

# Allow Okta to scan and discover AD attributes
# Review and confirm default mappings

Configure Import Settings

# Navigate to Directory Integrations > [Your AD Integration] > Settings

Import Settings:
- Import Schedule: Configure automatic sync frequency
- Import Scope: Verify OU selection
- Deactivation: Choose behavior for disabled AD users

Advanced Options:
- Group Import: Enable if syncing AD security groups
- Incremental Updates: Enable for efficient synchronization
- Conflict Resolution: Define handling of duplicate users

Step 4: Import and Activate Users

Initial User Import

# Import Users
1. Navigate to Directory Integrations > [Your AD Integration] > Import
2. Click "Import Now"
3. Select "Full Import" for initial synchronization
4. Review import preview and confirm assignments

# Review Imported Users
5. Go to Directory > People
6. Imported users appear with "Staged for activation" status
7. Review user details and attribute mapping accuracy

Activate Users

1. Select users in Directory > People
2. Click "Activate"
3. Users receive activation emails

1. Select multiple users
2. Choose "Activate" from bulk actions
3. Configure welcome email settings

Step 5: Ongoing Management and Monitoring

Monitor Synchronization Status

# Check Sync Health
Directory Integrations: View last sync status and errors
System Log: Monitor import events and conflicts
Agent Status: Verify agent connectivity and health

# Common Monitoring Points
- Failed user imports
- Attribute mapping conflicts
- Agent connectivity issues
- Sync schedule adherence

User Lifecycle Management

# User Updates
- Changes in AD automatically sync to Okta
- Attribute updates reflect based on configured mappings
- Group membership changes sync if group import enabled

# User Deactivation
- Disabled AD accounts can be automatically deactivated in Okta
- Configure deactivation policies in integration settings

Troubleshooting Common Issues