Skip to content

AADUser

Parameters

Parameter Attribute DataType Description Allowed Values
UserPrincipalName Key String The login name of the user
AccountEnabled Write Boolean Specifies whether the user account is enabled or not. Required when a user is created.
DisplayName Write String The display name for the user
GivenName Write String The first name of the user
Surname Write String The last name of the user
Roles Write String[] The list of Azure Active Directory roles assigned to the user.
UsageLocation Write String The country code the user will be assigned to
LicenseAssignment Write String[] The account SKU Id for the license to be assigned to the user
Password Write PSCredential The password for the account. The parameter is a PSCredential object, but only the Password component will be used. If Password is not supplied for a new resource a new random password will be generated. Property will only be used when creating the user and not on subsequent updates.
AgeGroup Write String Sets the age group of the user. Allowed values: null, Minor, NotAdult, and Adult. For more information, see legal age group property definitions. Minor, NotAdult, Adult
City Write String The City name of the user
Country Write String The Country name of the user
CompanyName Write String The company name which is associated with the user
Department Write String The Department name of the user
EmployeeHireDate Write String The date and time when the user was hired or will start work if there is a future hire. Supports $filter (eq, ne, not , ge, le, in).
EmployeeLeaveDateTime Write String The date and time when the user left or will leave the organization. To read this property, the calling app must be assigned the User-LifeCycleInfo.Read.All permission. To write this property, the calling app must be assigned the User.Read.All and User-LifeCycleInfo.ReadWrite.All permissions. To read this property in delegated scenarios, the admin needs at least one of the following Microsoft Entra roles: Lifecycle Workflows Administrator (least privilege), Global Reader. To write this property in delegated scenarios, the admin needs the Global Administrator role. Supports $filter (eq, ne, not , ge, le, in). For more information, see Configure the employeeLeaveDateTime property for a user.
EmployeeId Write String The employee identifier assigned to the user by the organization
EmployeeType Write String Captures enterprise worker type. For example, Employee, Contractor, Consultant, or Vendor.
FaxNumber Write String The Fax Number of the user
MemberOf Write String[] The Groups that the user is a direct member of
MobilePhone Write String The Mobile Phone Number of the user
OfficeLocation Write String The Office Name of the user
Mail Write String The mail address of the user
OtherMails Write String[] The other mails assigned to the user
PasswordPolicies Write String Specifies password policies for the user.
PhoneNumber Write String The Phone Number of the user
PostalCode Write String The Postal Code of the user
PreferredLanguage Write String The Preferred Language of the user
State Write String Specifies the state or province where the user is located
StreetAddress Write String Specifies the street address of the user
JobTitle Write String Specifies the title of the user
UserType Write String Specifies the title of the user Guest, Member, Other, Viral
OnPremisesExtensionAttributes Write MSFT_AADUserOnPremisesExtensionAttributes The on-premises extension attributes of the user. Can only be set for cloud-only users.
CustomSecurityAttributes Write MSFT_AADUserAttributeSet[] The list of custom security attributes attached to this user
Ensure Write String Present ensures the user exists, absent ensures it is removed Present, Absent
Credential Write PSCredential Credentials of the Exchange Global Admin
ApplicationId Write String Id of the Azure Active Directory application to authenticate with.
TenantId Write String Name of the Azure Active Directory tenant used for authentication. Format contoso.onmicrosoft.com
ApplicationSecret Write PSCredential Secret of the Azure Active Directory application used for authentication.
CertificateThumbprint Write String Thumbprint of the Azure Active Directory application's authentication certificate to use for authentication.
CertificatePassword Write PSCredential Username can be made up to anything but password will be used for CertificatePassword
CertificatePath Write String Path to certificate used in service principal usually a PFX file.
ManagedIdentity Write Boolean Managed ID being used for authentication.
AccessTokens Write String[] Access token used for authentication.

Embedded Instances

MSFT_AADUserOnPremisesExtensionAttributes

Parameters

Parameter Attribute DataType Description Allowed Values
ExtensionAttribute1 Write String First customizable extension attribute.
ExtensionAttribute2 Write String Second customizable extension attribute.
ExtensionAttribute3 Write String Third customizable extension attribute.
ExtensionAttribute4 Write String Fourth customizable extension attribute.
ExtensionAttribute5 Write String Fifth customizable extension attribute.
ExtensionAttribute6 Write String Sixth customizable extension attribute.
ExtensionAttribute7 Write String Seventh customizable extension attribute.
ExtensionAttribute8 Write String Eighth customizable extension attribute.
ExtensionAttribute9 Write String Ninth customizable extension attribute.
ExtensionAttribute10 Write String Tenth customizable extension attribute.
ExtensionAttribute11 Write String Eleventh customizable extension attribute.
ExtensionAttribute12 Write String Twelfth customizable extension attribute.
ExtensionAttribute13 Write String Thirteenth customizable extension attribute.
ExtensionAttribute14 Write String Fourteenth customizable extension attribute.
ExtensionAttribute15 Write String Fifteenth customizable extension attribute.

MSFT_AADUserAttributeSet

Parameters

Parameter Attribute DataType Description Allowed Values
AttributeSetName Required String Attribute Set Name.
AttributeValues Write MSFT_AADUserAttributeValue[] List of attribute values.

MSFT_AADUserAttributeValue

Parameters

Parameter Attribute DataType Description Allowed Values
AttributeName Required String Name of the Attribute
StringArrayValue Write String[] If the attribute has a string array value
IntArrayValue Write UInt32[] If the attribute has a int array value
StringValue Write String If the attribute has a string value
IntValue Write UInt32 If the attribute has a int value
BoolValue Write Boolean If the attribute has a boolean value

Description

This resource allows users to create Azure AD Users and assign them licenses, roles and/or groups.

If using with AADGroup, be aware that if AADUser->MemberOf is being specified and the referenced group is configured with AADGroup->Member then a conflict may arise if the two don't match. It is usually best to choose only one of them. See AADGroup

Permissions

Graph

To authenticate with the Graph API, this resource requires the following permissions:

Delegated permissions

  • Read

  • RoleManagement.Read.Directory, User.Read.All, User-LifeCycleInfo.Read.All, GroupMember.Read.All, CustomSecAttributeAssignment.Read.All

  • Update

  • Organization.Read.All, RoleManagement.ReadWrite.Directory, User.EnableDisableAccount.All, User.ReadWrite.All, User-LifeCycleInfo.ReadWrite.All, User.DeleteRestore.All, Group.ReadWrite.All, GroupMember.ReadWrite.All, CustomSecAttributeAssignment.ReadWrite.All

Application permissions

  • Read

  • RoleManagement.Read.Directory, User.Read.All, User-LifeCycleInfo.Read.All, GroupMember.Read.All, CustomSecAttributeAssignment.Read.All

  • Update

  • Organization.Read.All, RoleManagement.ReadWrite.Directory, User.EnableDisableAccount.All, User.ReadWrite.All, User-LifeCycleInfo.ReadWrite.All, User.DeleteRestore.All, Group.ReadWrite.All, GroupMember.ReadWrite.All, CustomSecAttributeAssignment.ReadWrite.All

Examples

Example 1

This example is used to test new resources and showcase the usage of new resources being worked on. It is not meant to use as a production baseline.

Configuration Example
{
    param
    (
        [Parameter()]
        [System.String]
        $ApplicationId,

        [Parameter()]
        [System.String]
        $TenantId,

        [Parameter()]
        [System.String]
        $CertificateThumbprint
    )

    Import-DscResource -ModuleName Microsoft365DSC

    Node localhost
    {
        AADUser 'AADUser-Example'
        {
            UserPrincipalName     = "John.Smith@$TenantId"
            GivenName             = "John"
            Surname               = "Smith"
            DisplayName           = "John J. Smith"
            AgeGroup              = "Adult"
            City                  = "Gatineau"
            Country               = "Canada"
            OfficeLocation        = "Ottawa - Queen"
            UsageLocation         = "US"
            CustomSecurityAttributes = @(
                MSFT_AADUserAttributeSet{
                    AttributeSetName = 'Engineering'
                    AttributeValues  = @(
                        MSFT_AADUserAttributeValue{
                            AttributeName    = 'Project'
                            StringArrayValue = @('Baker', 'Cascade')
                        }
                        MSFT_AADUserAttributeValue{
                            AttributeName = 'Datacenter'
                            StringValue   = 'Seattle'
                        }
                    )
                }
            )
            OnPremisesExtensionAttributes = MSFT_AADUserOnPremisesExtensionAttributes{
                ExtensionAttribute1 = "Head Office"
                ExtensionAttribute2 = "Cost Center 4100"
            }
            AccountEnabled        = $true
            CompanyName           = "Contoso"
            Department            = "Human Resources"
            EmployeeHireDate      = "2026-01-01T00:00:00.0000000Z"
            EmployeeId            = "E1234567"
            EmployeeLeaveDateTime = "2027-06-30T00:00:00.0000000Z"
            EmployeeType          = "Employee"
            JobTitle              = "Senior Program Manager"
            StreetAddress         = "100 Rue Principale"
            State                 = "Quebec"
            PostalCode            = "K1A 0B1"
            PhoneNumber           = "+1 613 555 0100"
            MobilePhone           = "+1 613 555 0177"
            FaxNumber             = "+1 613 555 0143"
            OtherMails            = @("john.smith.contoso@outlook.com")
            PreferredLanguage     = "en-US"
            PasswordPolicies      = "DisablePasswordExpiration"
            UserType              = "Member"
            Ensure                = "Present"
            ApplicationId         = $ApplicationId
            TenantId              = $TenantId
            CertificateThumbprint = $CertificateThumbprint
        }
    }
}

Example 2

This example is used to test new resources and showcase the usage of new resources being worked on. It is not meant to use as a production baseline.

Configuration Example
{
    param
    (
        [Parameter()]
        [System.String]
        $ApplicationId,

        [Parameter()]
        [System.String]
        $TenantId,

        [Parameter()]
        [System.String]
        $CertificateThumbprint
    )

    Import-DscResource -ModuleName Microsoft365DSC

    Node localhost
    {
        AADUser 'AADUser-Example'
        {
            UserPrincipalName     = "John.Smith@$TenantId"
            GivenName             = "John"
            Surname               = "Smith"
            DisplayName           = "John J. Smith"
            AgeGroup              = "Adult"
            City                  = "Ottawa" # Updated Property
            Country               = "Canada"
            OfficeLocation        = "Ottawa - Queen"
            UsageLocation         = "US"
            CustomSecurityAttributes = @(
                MSFT_AADUserAttributeSet{
                    AttributeSetName = 'Engineering'
                    AttributeValues  = @(
                        MSFT_AADUserAttributeValue{
                            AttributeName    = 'Project'
                            StringArrayValue = @('Baker', 'Cascade', 'Denali') # Updated
                        }
                        MSFT_AADUserAttributeValue{
                            AttributeName = 'Datacenter'
                            StringValue   = 'Portland' # Updated
                        }
                    )
                }
            )
            OnPremisesExtensionAttributes = MSFT_AADUserOnPremisesExtensionAttributes{
                ExtensionAttribute1 = "Head Office"
                ExtensionAttribute2 = "Cost Center 4100"
            }
            AccountEnabled        = $true
            CompanyName           = "Contoso"
            Department            = "Human Resources"
            EmployeeHireDate      = "2026-01-01T00:00:00.0000000Z"
            EmployeeId            = "E1234567"
            EmployeeLeaveDateTime = "2027-06-30T00:00:00.0000000Z"
            EmployeeType          = "Employee"
            JobTitle              = "Senior Program Manager"
            StreetAddress         = "100 Rue Principale"
            State                 = "Quebec"
            PostalCode            = "K1A 0B1"
            PhoneNumber           = "+1 613 555 0100"
            MobilePhone           = "+1 613 555 0177"
            FaxNumber             = "+1 613 555 0143"
            OtherMails            = @("john.smith.contoso@outlook.com")
            PreferredLanguage     = "en-US"
            PasswordPolicies      = "DisablePasswordExpiration"
            UserType              = "Member"
            Ensure                = "Present"
            ApplicationId         = $ApplicationId
            TenantId              = $TenantId
            CertificateThumbprint = $CertificateThumbprint
        }
    }
}

Example 3

This example is used to test new resources and showcase the usage of new resources being worked on. It is not meant to use as a production baseline.

Configuration Example
{
    param
    (
        [Parameter()]
        [System.String]
        $ApplicationId,

        [Parameter()]
        [System.String]
        $TenantId,

        [Parameter()]
        [System.String]
        $CertificateThumbprint
    )

    Import-DscResource -ModuleName Microsoft365DSC

    Node localhost
    {
        AADUser 'AADUser-Example'
        {
            UserPrincipalName     = "John.Smith@$TenantId"
            Ensure                = "Absent"
            ApplicationId         = $ApplicationId
            TenantId              = $TenantId
            CertificateThumbprint = $CertificateThumbprint
        }
    }
}