Public/Connect-UserProvisioning.ps1
|
<# .DESCRIPTION Connects the UserWriteback module to Entra ID and Active Directory. .SYNOPSIS Connects the UserWriteback module to Entra ID and Active Directory. .EXAMPLE Import-Module EntraIDAccessToken Import-Module Fortytwo.IAM.UserWriteback Add-EntraIDClientSecretAccessTokenProfile ` -TenantId "bb73082a-b74c-4d39-aec0-41c77d6f4850" ` -ClientId "78f07963-ce55-4b23-b56a-2e13f2036d7f" Connect-UserWriteback .EXAMPLE Connect-UserProvisioning ` -GroupObjectId "e687aa72-455f-48f1-ade3-4232e8fa2849" ` -DefaultDestinationOU "OU=User writeback,DC=corp,DC=goodworkaround,DC=com" ` -DisableExtensionAttributeMapping ` -Verbose #> function Connect-UserProvisioning { [CmdletBinding()] Param( # Access token profile to use for authentication for Fortytwo IAM Core. The EntraIDAccessToken module must be installed and imported. [Parameter(Mandatory = $false)] [string]$AccessTokenProfile = "default", # OU included in the synchronization scope. Only users in these OUs will be sent to the connector space. If not specified, all OUs are included. [Parameter(Mandatory = $false)] [string[]]$IncludedOUs, # Properties of the user objects to retrieve from Active Directory. If not specified, all properties are retrieved. [Parameter(Mandatory = $false)] [string[]]$UserProperties = @("*"), # Properties of the user objects to retrieve from Active Directory. If not specified, all properties are retrieved. [Parameter(Mandatory = $false)] [string]$LifeCycleStateAttribute = "msDS-cloudExtensionAttribute20", # Default OU to provision users into in Active Directory. Must be a valid distinguished name of an existing OU in Active Directory. [Parameter(Mandatory = $true)] [string]$DefaultDestinationOU, # Keep user disabled or days before deletion [Parameter(Mandatory = $false)] [ValidateRange(0, [int]::MaxValue)] [int]$DeleteUsersAfterDays = 180, # Connector id of the connector in Fortytwo IAM Core. This is used for logging and to link the operations to the correct connector in Fortytwo IAM Core. Must be a valid GUID. [Parameter(Mandatory = $true)] [ValidatePattern("^[a-z0-9]{8}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{12}$", ErrorMessage = "ConnectorId must be a valid GUID.")] [string]$ConnectorId, # Skip all tests during connection. Not recommended, useful for pester testing [Parameter(Mandatory = $false)] [Switch] $SkipAllTests ) Process { $Script:AccessTokenProfile = $AccessTokenProfile $Script:IncludedOUs = $IncludedOUs $Script:UserProperties = $UserProperties $Script:DefaultDestinationOU = $DefaultDestinationOU $Script:ConnectorId = $ConnectorId $Script:LifeCycleStateAttribute = $LifeCycleStateAttribute $Script:DeleteUsersAfterDays = $DeleteUsersAfterDays if ($SkipAllTests.IsPresent) { Write-Warning "⚠️ Skipping all connection tests. Proceed with caution!" } else { if (!(Get-EntraIDAccessToken -Profile $AccessTokenProfile | Get-EntraIDAccessTokenHasRoles -Roles "iam-core.connector-data.readwrite.self" -Any)) { Write-Warning "The access token profile '$AccessTokenProfile' does not have the required role 'iam-core.connector-data.readwrite.self'. Please ensure the profile is correct and has the necessary permissions." } else { Write-Verbose "✅ The access token profile '$AccessTokenProfile' has the required role 'iam-core.connector-data.readwrite.self'." } if (!(Get-EntraIDAccessToken -Profile $AccessTokenProfile | Get-EntraIDAccessTokenHasRoles -Roles "changeemail.emailaddress.generate.all" -Any)) { Write-Warning "The access token profile '$AccessTokenProfile' does not have the required role 'changeemail.emailaddress.generate.all'. Please ensure the profile is correct and has the necessary permissions." } else { Write-Verbose "✅ The access token profile '$AccessTokenProfile' has the required role 'changeemail.emailaddress.generate.all'." } # Verify that the default OU exists in Active Directory if (-not (Get-ADOrganizationalUnit -Filter "DistinguishedName -eq '$DefaultDestinationOU'" -ErrorAction SilentlyContinue)) { throw "The specified DefaultDestinationOU '$DefaultDestinationOU' does not exist in Active Directory. Please verify the DefaultDestinationOU parameter." } else { Write-Verbose "✅ OU '$DefaultDestinationOU' exists in Active Directory." } # Verify that all included OUs exist in Active Directory if ($IncludedOUs) { if ($DefaultDestinationOU -notin $IncludedOUs) { Write-Warning "The specified DefaultDestinationOU '$DefaultDestinationOU' is not included in the IncludedOUs list. This may lead to provisioning failures as the default OU is outside of the synchronization scope. Please ensure the DefaultDestinationOU is included in the IncludedOUs parameter." } foreach ($OU in $IncludedOUs) { if (-not (Get-ADOrganizationalUnit -Filter "DistinguishedName -eq '$OU'" -ErrorAction SilentlyContinue)) { throw "The specified included OU '$OU' does not exist in Active Directory. Please verify the IncludedOUs parameter." } else { Write-Verbose "✅ OU '$OU' exists in Active Directory." } } } } # Connect using the connector module Connect-Connector -AccessTokenProfile $AccessTokenProfile -ConnectorId $ConnectorId -Environment ($ENV:IAMCOREENVIRONMENT ? $ENV:IAMCOREENVIRONMENT : "Production") Write-Verbose "✅ Connected to Fortytwo IAM Core with ConnectorId '$ConnectorId' using AccessTokenProfile '$AccessTokenProfile'" } } |