Object Provisioning

When AAD Connect provisions an on-premises object to Azure AD, it populates a cloud attribute to link it to the on-premises object.

This attribute, known as the ImmutableId, derives from an encoded representation of the sourceAnchor attribute. The sourceAnchor itself, is usually the ms-DS-ConsistencyGuid attribute and based upon the underlying objectGuid of the AD object.

It helps to think of it as a declarative link, essentially saying that it synchronises from an on-premises object. AAD Connect uses this principle to match the object (linking it) to maintain the attribute flow.

Despite its name, the ImmutableId may be changed under certain advanced scenarios. For instance, when performing a cloud tenant migration it may be necessary to create placeholder (cloud only) accounts to receive migration data. At a later stage these may have their ImmutableIds added so that they may be re-linked to their on-premises accounts (enabling their password hash flow and other attributes)

Converting the ImmutableId

The following functions provide the conversions; to and from the encoded ImmutableId value as well as a means to construct the DN for an object as shown in AAD Connect.

Converstion from ImmutableId to GUID

function ConvertFrom-ImmutableIdToConsistencyGuid {
    <#
    .SYNOPSIS
        Immutable ID to Consistency GUID
    .DESCRIPTION
    #>
    [CmdletBinding()]
    [OutputType([GUID])]
    param
    (
        [Parameter(
            Mandatory = $true,
            ValueFromPipelineByPropertyName = $true,
            Position = 0)]
        [ValidateNotNullOrEmpty()]
        [String]
        $ImmutableId
    )
    process {
        [GUID][System.Convert]::FromBase64String($ImmutableID)
    }
}

Converstion from GUID to ImmutableId

function ConvertFrom-ConsistencyGuidToImmutableId {
    <#
    .SYNOPSIS
        Consistency GUID to Immutable ID
    .DESCRIPTION
    #>
    [CmdletBinding()]
    [OutputType([String])]
    param
    (
        [Parameter(
            Mandatory = $true,
            ValueFromPipelineByPropertyName = $true,
            Position = 0)]
        [ValidateNotNullOrEmpty()]
        [GUID]
        $ConsistencyGuid
    )
    process {
        [System.Convert]::ToBase64String($ConsistencyGuid.ToByteArray())
    }
}

Converstion from ImmutableId to DN

Conversion from ImmutableId to DN as shown in AAD Connect.

function ConvertFrom-ImmutableIdToDn {
    <#
    .SYNOPSIS
        Converts an Immutable ID to a DN (as displayed in AAD Connect)
    .DESCRIPTION
    #>
    [CmdletBinding()]
    [OutputType([string])]
    param (
        [Parameter(
            Mandatory = $true,
            ValueFromPipelineByPropertyName = $true,
            Position = 0)]
        [ValidateScript( { try { $null = [Convert]::FromBase64String($_); $true } catch { $false } })]
        [String]
        $ImmutableId
    )  
    process {
        $encodedValue = ([Text.Encoding]::UTF8).getbytes($ImmutableId)
        $dn = $encodedValue | ForEach-Object { ([Convert]::ToString($_, 16)) }
        $dn = $dn -join ''
        "CN={$dn}"
    }     
}