Setting property values

The Account options flags are set by modifying the userAccountControl property. Each flag has a corresponding integer value, and these values are cumulative. For a complete list of flags and their integer representations, see the ADS_USER_FLAG_ENUM enumerator. Here are some of the frequently used combinations:

Examples

Set the account options to Cannot change password and Password never expires:

{
    "propertyName": "userAccountControl",
    "propertyType": "Integer",
    "values": [ 65600 ]
}

To change specific flags of an existing account without changing other flags, you need add the mask attribute to the request body.

{
    "propertyName": "userAccountControl",
    "propertyType": "Integer",
    "values": [ 2 ],
    "mask": 65538
}

{
    "propertyName": "userAccountControl",
    "propertyType": "Integer",
    "values": [ 2 ],
    "mask": 2
}

{
    "propertyName": "userAccountControl",
    "propertyType": "Integer",
    "values": [ 0 ],
    "mask": 2
}

{
    "propertyName": "userAccountControl",
    "propertyType": "Integer",
    "values": [ 66 ],
    "mask": -2147483582
}

{
    "propertyName": "userAccountControl",
    "propertyType": "Integer",
    "values": [ 0 ],
    "mask": 66
}

Active Directory groups

The group type and scope is set by modifying the groupType property. Specify the required combination of group scope and group type as the property value. For a list of group types/scopes and their integer representations, see the ADS_GROUP_TYPE_ENUM enumerator.

Examples

Make the group a Universal distribution group:

{
    "propertyName": "groupType",
    "propertyType": "Integer",
    "values": [ 8 ]
}

To change the group type or scope independently of each other, you need add the mask attribute to the request body.

{
    "propertyName": "groupType",
    "propertyType": "Integer",
    "values": [ 0 ],
    "mask": -2147483648
}

{
    "propertyName": "groupType",
    "propertyType": "Integer",
    "values": [ 2 ],
    "mask": 14
}

Microsoft Entra groups

The group type for Microsoft Entra groups is determined during creation and can't be changed afterwards. The group type is set by modifying the adm-AzureGroupType property. Here are all the possible values.

Examples

Make the group a Mail-enabled security group:

{
    "propertyName": "adm-AzureGroupType",
    "propertyType": "Integer",
    "values": [ 3 ]
}

Logon hours are represented as an array of 21 bytes, with 3 bytes per day and 1 bit per hour. The first bit in the array is Sunday, 00:00 to 0:59 in the UTC time zone, the second bit is Sunday, 01:00 to 01:59, and so on. A bit set to 1 means logon during this hour is allowed, and 0 means logon is not allowed.

The following code sample creates the logon hours value, where logon is allowed on Monday (9am-5pm) and Tuesday (11am-3pm):

class LogonDay {
   [DayOfWeek]$DayOfWeek
   [Int]$StartHour
   [Int]$NumHours
}

# Allow logon during specific hours on Monday and Tuesday
[LogonDay[]]$allowedLogon = @(
   [LogonDay]@{DayOfWeek="Monday"; StartHour=9; NumHours=8}  # Monday 9AM - 5PM
   [LogonDay]@{DayOfWeek="Tuesday"; StartHour=11; NumHours=4}  # Tuesday 11AM - 3PM
)

# Create an empty byte array and populate it with the specified logon hours in the local time zone
[Byte[]]$logonHours = @(0) * 21
$timeZoneOffset = -[System.TimeZoneInfo]::Local.BaseUtcOffset.Hours
foreach ($day in $allowedLogon)
{
   $endHour = $day.StartHour + $day.NumHours
   for ($hour = $day.StartHour; $hour -lt $endHour; $hour++)
   {
       $byteIndex = (($hour - ($hour % 8)) / 8) + $day.DayOfWeek * 3 # 3 bytes per day
       $bitIndex = (($hour % 8) + $byteIndex * 8)
       $totalBitCount = 168 # 21 byte * 8 bits in byte
       $bitIndex = ((($bitIndex + $timeZoneOffset) % $totalBitCount) + $totalBitCount) % $totalBitCount
       $byteIndex = [System.Math]::Floor([Decimal]($bitIndex / 8))
       $bitInByteIndex = $bitIndex % 8
       $logonHours[$byteIndex] = $logonHours[$byteIndex] -bor [Byte](1 -shl $bitInByteIndex)
   }
}

To set logon hours, convert the resulting byte array into a Base64-encoded string:

$value = [Convert]::ToBase64String($logonHours)

Specify this Base-64 encoded string in the corresponding element of the request body:

{
    "propertyName": "logonHours",
    "propertyType": "Binary",
    "values": [ "AAAAAMA/AAAPAAAAAAAAAAAAAAAA" ]
}

Values for timestamp properties (e.g. Account expires, Password last set, adm-CustomAttributeTimestamp1) can be specified in the following way:

• "Never"
• "Unspecified"
• Specific date

It is recommended to specify the date in the ISO 8601 format:

• 2020-10-22T06:00:00+03:00

However, many other formats will also be accepted, for example:

• 2020-10-22 06:00 +3
• 06.00 22/10/2020 +3:00
• 6AM 22.10.2020 +3

Use the following virtual properties to manipulate the user's Microsoft 365 account and their license assignments.

If a user doesn't have a Microsoft 365 account, you must set adm-O365AccountLocation and adm-O365AccountBlocked in a single request to activate their account. Assigning licenses during account activation is possible but optional. After that, you can modify any of the Microsoft 365 virtual properties individually in all subsequent requests.

Usage location and sign-in status

Usage location and sign-in status are set just like any property.

{
    "propertyName": "adm-O365AccountLocation",
    "propertyType": "String",
    "values": [ "US" ]
},
{
    "propertyName": "adm-O365AccountBlocked",
    "propertyType": "Boolean",
    "values": [ true ]
}

License assignments

To assign licenses to a user, use the following property modification structure.

{
    "propertyName": "adm-O365AccountLicenses",
    "propertyType": "M365Licenses",
    "values": [ 
        {
            "licenses": string[],
            "apps": string[]
        } 
    ]
}

licenses array

An array that contains the SKU part numbers (e.g. ENTERPRISEPACK) of every license that the user should have.

• If the array contains a license and a user doesn't have it, it will be assigned.
• If the array doesn't contain a license that a user has, it will be revoked.

apps array, optional

An array that contains the service plan identifiers (e.g. EXCHANGEENTERPRISE) of apps that should be enabled. Include this attribute in the request only if you want to granularly enable apps. If the attribute is not included, all apps that belong to the selected licenses will be enabled.

Examples

The following property modification assigns Microsoft 365 F1 with a select few apps enabled:

• Microsoft Entra ID P1
• Azure Information Protection Premium P1
• Exchange Foundation
• Microsoft Azure Multi-Factor Authentication
• Microsoft Teams

{
    "propertyName": "adm-O365AccountLicenses",
    "propertyType": "M365Licenses",
    "values": [ 
        {
            "licenses": [
                "M365_F1"
            ],
            "apps": [
                "AAD_PREMIUM",
                "RMS_S_PREMIUM",
                "EXCHANGE_S_FOUNDATION",
                "MFA_PREMIUM",
                "TEAMS1"
            ]
        } 
    ]
}