Tutorial: Migrate SSO Applications from Okta to Entra ID¶

# Connect to Microsoft Graph
Connect-MgGraph -Scopes "Application.ReadWrite.All", "AppRoleAssignment.ReadWrite.All"

# Find Salesforce in the gallery
$templates = Get-MgApplicationTemplate -Filter "displayName eq 'Salesforce'"
$salesforceTemplate = $templates | Select-Object -First 1

Write-Host "Gallery template found: $($salesforceTemplate.DisplayName) ($($salesforceTemplate.Id))"

# Instantiate the gallery application
$result = Invoke-MgInstantiateApplicationTemplate -ApplicationTemplateId $salesforceTemplate.Id `
    -Body @{ displayName = "Salesforce" }

$appId = $result.Application.AppId
$spId = $result.ServicePrincipal.Id
Write-Host "Enterprise Application created:"
Write-Host "  App ID: $appId"
Write-Host "  Service Principal ID: $spId"

# Set preferred SSO mode to SAML
Update-MgServicePrincipal -ServicePrincipalId $spId -PreferredSingleSignOnMode "saml"

# Configure SAML URLs (from Okta application settings)
# Get these values from Okta admin console > Applications > Salesforce > Sign On tab
$samlConfig = @{
    web = @{
        redirectUris = @(
            "https://contoso.my.salesforce.com?so=00D000000000001"
        )
    }
    identifierUris = @(
        "https://contoso.my.salesforce.com"
    )
}

Update-MgApplication -ApplicationId $result.Application.Id -BodyParameter $samlConfig

Write-Host "SAML SSO configured for Salesforce"

# Map Okta SAML attribute statements to Entra claims
# Okta attribute statements (from export):
#   user.email -> emailAddress
#   user.firstName -> firstName
#   user.lastName -> lastName
#   user.login -> federationIdentifier

# In Entra, configure claims via the admin center:
# Enterprise Applications > Salesforce > Single sign-on > Attributes & Claims

# Or via Graph API:
$claimsMapping = @{
    claimsMappingPolicies = @(
        @{
            displayName = "Salesforce Claims Policy"
            definition = @(
                '{"ClaimsMappingPolicy":{"Version":1,"IncludeBasicClaimSet":"true","ClaimsSchema":[{"Source":"user","ID":"mail","SamlClaimType":"http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress"},{"Source":"user","ID":"givenname","SamlClaimType":"http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname"},{"Source":"user","ID":"surname","SamlClaimType":"http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname"},{"Source":"user","ID":"userprincipalname","SamlClaimType":"http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier"}]}}'
            )
        }
    )
}

# Apply claims mapping policy to service principal
# This is typically done via the Entra admin center for gallery apps
Write-Host "Configure claims via: Entra admin center > Enterprise Applications > Salesforce > Single sign-on > Attributes & Claims"

# Get the SAML metadata URL for Salesforce
$tenantId = (Get-MgContext).TenantId
$metadataUrl = "https://login.microsoftonline.com/$tenantId/federationmetadata/2007-06/federationmetadata.xml?appid=$appId"

Write-Host "SAML Metadata URL: $metadataUrl"
Write-Host ""
Write-Host "Configure this in Salesforce:"
Write-Host "  1. Go to Salesforce Setup > Identity > Single Sign-On Settings"
Write-Host "  2. Upload metadata from: $metadataUrl"
Write-Host "  3. Or manually configure:"

# Get signing certificate
$loginUrl = "https://login.microsoftonline.com/$tenantId/saml2"
$logoutUrl = "https://login.microsoftonline.com/$tenantId/saml2"
$entityId = "https://sts.windows.net/$tenantId/"

Write-Host "  Entity ID: $entityId"
Write-Host "  SSO URL: $loginUrl"
Write-Host "  SLO URL: $logoutUrl"

# Create a new application registration
$customApp = New-MgApplication -DisplayName "Internal HR Portal" `
    -SignInAudience "AzureADMyOrg" `
    -IdentifierUris @("https://hr-portal.contoso.com") `
    -Web @{
        RedirectUris = @("https://hr-portal.contoso.com/saml/acs")
    }

# Create service principal
$customSp = New-MgServicePrincipal -AppId $customApp.AppId

# Set SSO mode to SAML
Update-MgServicePrincipal -ServicePrincipalId $customSp.Id -PreferredSingleSignOnMode "saml"

Write-Host "Custom SAML app created:"
Write-Host "  Display Name: Internal HR Portal"
Write-Host "  App ID: $($customApp.AppId)"
Write-Host "  SP ID: $($customSp.Id)"

# Map Okta attribute statements to Entra claims
# Okta had these custom attribute statements:
#   user.employeeNumber -> employeeId
#   user.department -> department
#   user.title -> jobTitle
#   appuser.role -> customRole (app-specific attribute)

Write-Host "Configure custom claims in Entra admin center:"
Write-Host "  Enterprise Applications > Internal HR Portal > Single sign-on > Attributes & Claims"
Write-Host ""
Write-Host "  Add the following claims:"
Write-Host "  1. employeeId -> Source: user.employeeid"
Write-Host "  2. department -> Source: user.department"
Write-Host "  3. jobTitle -> Source: user.jobtitle"
Write-Host "  4. customRole -> Source: user.assignedroles (or app role)"

# Create OIDC application registration
$oidcApp = New-MgApplication -DisplayName "Internal Dashboard (OIDC)" `
    -SignInAudience "AzureADMyOrg" `
    -Web @{
        RedirectUris = @(
            "https://dashboard.contoso.com/auth/callback",
            "https://dashboard.contoso.com/auth/silent-renew"
        )
        ImplicitGrantSettings = @{
            EnableIdTokenIssuance = $true
            EnableAccessTokenIssuance = $false
        }
    }

# Create client secret
$secret = Add-MgApplicationPassword -ApplicationId $oidcApp.Id -PasswordCredential @{
    DisplayName = "Dashboard client secret"
    EndDateTime = (Get-Date).AddYears(2)
}

# Output configuration for application team
$tenantId = (Get-MgContext).TenantId

Write-Host "`n=== OIDC Application Configuration ==="
Write-Host "Update your application's OIDC configuration:"
Write-Host ""
Write-Host "  # Old Okta configuration (replace these):"
Write-Host "  # OIDC_ISSUER=https://your-org.okta.com/oauth2/default"
Write-Host "  # OIDC_CLIENT_ID=okta-client-id"
Write-Host "  # OIDC_CLIENT_SECRET=okta-client-secret"
Write-Host ""
Write-Host "  # New Entra ID configuration:"
Write-Host "  OIDC_ISSUER=https://login.microsoftonline.com/$tenantId/v2.0"
Write-Host "  OIDC_CLIENT_ID=$($oidcApp.AppId)"
Write-Host "  OIDC_CLIENT_SECRET=$($secret.SecretText)"
Write-Host "  OIDC_AUTHORITY=https://login.microsoftonline.com/$tenantId"
Write-Host "  OIDC_TOKEN_ENDPOINT=https://login.microsoftonline.com/$tenantId/oauth2/v2.0/token"
Write-Host "  OIDC_AUTHORIZE_ENDPOINT=https://login.microsoftonline.com/$tenantId/oauth2/v2.0/authorize"
Write-Host ""
Write-Host "  IMPORTANT: Save the client secret securely. It will not be shown again."

# Create a group for SSO testing
$testGroup = New-MgGroup -DisplayName "SSO-Migration-Test" `
    -Description "Test group for SSO migration validation" `
    -MailEnabled:$false `
    -MailNickname "SSOMigrationTest" `
    -SecurityEnabled:$true

# Add test users
$testUsers = @("test-user1@contoso.com", "test-user2@contoso.com", "test-user3@contoso.com")
foreach ($upn in $testUsers) {
    $user = Get-MgUser -Filter "userPrincipalName eq '$upn'"
    New-MgGroupMember -GroupId $testGroup.Id -DirectoryObjectId $user.Id
}

# Assign group to each migrated application
$apps = @("Salesforce", "Internal HR Portal", "Internal Dashboard (OIDC)")
foreach ($appName in $apps) {
    $sp = Get-MgServicePrincipal -Filter "displayName eq '$appName'"
    if ($sp) {
        New-MgServicePrincipalAppRoleAssignment -ServicePrincipalId $sp.Id -Body @{
            principalId = $testGroup.Id
            resourceId = $sp.Id
            appRoleId = "00000000-0000-0000-0000-000000000000"  # Default access
        }
        Write-Host "Assigned $appName to test group"
    }
}

# Generate test URLs
$tenantId = (Get-MgContext).TenantId

foreach ($appName in $apps) {
    $sp = Get-MgServicePrincipal -Filter "displayName eq '$appName'"
    if ($sp) {
        Write-Host "`nTest SSO for: $appName"
        Write-Host "  My Apps URL: https://myapps.microsoft.com"
        Write-Host "  Direct SSO test: https://login.microsoftonline.com/$tenantId/saml2?SAMLRequest=..."
        Write-Host "  Admin test: Entra admin center > Enterprise Applications > $appName > Single sign-on > Test"
    }
}

# Check sign-in logs for test applications
foreach ($appName in $apps) {
    $sp = Get-MgServicePrincipal -Filter "displayName eq '$appName'"
    if ($sp) {
        $signIns = Get-MgAuditLogSignIn `
            -Filter "appId eq '$($sp.AppId)' and createdDateTime ge $(Get-Date (Get-Date).AddHours(-24) -Format 'yyyy-MM-ddTHH:mm:ssZ')" `
            -Top 20

        Write-Host "`n$appName sign-in results (last 24 hours):"
        if ($signIns.Count -eq 0) {
            Write-Host "  No sign-in attempts recorded" -ForegroundColor Yellow
        } else {
            $signIns | ForEach-Object {
                $status = if ($_.Status.ErrorCode -eq 0) { "OK" } else { "FAIL ($($_.Status.ErrorCode))" }
                Write-Host "  $($_.UserPrincipalName): $status at $($_.CreatedDateTime)"
            }
        }
    }
}

# For each application, migrate assignments from Okta groups to Entra groups
# This example migrates the full user base for Salesforce

$salesforceSp = Get-MgServicePrincipal -Filter "displayName eq 'Salesforce'"

# Option A: Assign an existing Entra security group
$salesforceGroup = Get-MgGroup -Filter "displayName eq 'Salesforce-Users'"
New-MgServicePrincipalAppRoleAssignment -ServicePrincipalId $salesforceSp.Id -Body @{
    principalId = $salesforceGroup.Id
    resourceId = $salesforceSp.Id
    appRoleId = "00000000-0000-0000-0000-000000000000"
}

# Option B: Assign individual users (for apps with specific role mappings)
# Export Okta assignments and recreate in Entra
$oktaAssignments = Get-Content "assignments-okta-app-id.json" | ConvertFrom-Json

foreach ($assignment in $oktaAssignments) {
    # Map Okta user ID to Entra user
    # This requires a mapping table or matching by email/UPN
    $user = Get-MgUser -Filter "userPrincipalName eq '$($assignment.email)'"
    if ($user) {
        New-MgServicePrincipalAppRoleAssignment -ServicePrincipalId $salesforceSp.Id -Body @{
            principalId = $user.Id
            resourceId = $salesforceSp.Id
            appRoleId = "00000000-0000-0000-0000-000000000000"
        }
    }
}

Write-Host "User assignments migrated for Salesforce"