Azure Active Directory version 2 cmdlets for group management

This article contains examples of how to use PowerShell to manage your groups in Azure Active Directory (Azure AD). It also tells you how to get set up with the Azure AD PowerShell module. First, you must download the Azure AD PowerShell module.

Install the Azure AD PowerShell module

To install the Azure AD PowerShell module, use the following commands:

PS C:\Windows\system32> install-module azuread
PS C:\Windows\system32> import-module azuread

To verify that the module is ready to use, use the following command:

PS C:\Windows\system32> get-module azuread

ModuleType Version      Name                                ExportedCommands
---------- ---------    ----                                ----------------
Binary     2.0.0.115    azuread                      {Add-AzureADAdministrati...}

Now you can start using the cmdlets in the module. For a full description of the cmdlets in the Azure AD module, please refer to the online reference documentation for Azure Active Directory PowerShell Version 2.

Connect to the directory

Before you can start managing groups using Azure AD PowerShell cmdlets, you must connect your PowerShell session to the directory you want to manage. Use the following command:

PS C:\Windows\system32> Connect-AzureAD

The cmdlet prompts you for the credentials you want to use to access your directory. In this example, we are using karen@drumkit.onmicrosoft.com to access the demonstration directory. The cmdlet returns a confirmation to show the session was connected successfully to your directory:

Account                       Environment Tenant
-------                       ----------- ------
Karen@drumkit.onmicrosoft.com AzureCloud  85b5ff1e-0402-400c-9e3c-0f…

Now you can start using the AzureAD cmdlets to manage groups in your directory.

Retrieve groups

To retrieve existing groups from your directory, use the Get-AzureADGroups cmdlet.

To retrieve all groups in the directory, use the cmdlet without parameters:

PS C:\Windows\system32> get-azureadgroup

The cmdlet returns all groups in the connected directory.

You can use the -objectID parameter to retrieve a specific group for which you specify the group’s objectID:

PS C:\Windows\system32> get-azureadgroup -ObjectId e29bae11-4ac0-450c-bc37-6dae8f3da61b

The cmdlet now returns the group whose objectID matches the value of the parameter you entered:

DeletionTimeStamp            :
ObjectId                     : e29bae11-4ac0-450c-bc37-6dae8f3da61b
ObjectType                   : Group
Description                  :
DirSyncEnabled               :
DisplayName                  : Pacific NW Support
LastDirSyncTime              :
Mail                         :
MailEnabled                  : False
MailNickName                 : 9bb4139b-60a1-434a-8c0d-7c1f8eee2df9
OnPremisesSecurityIdentifier :
ProvisioningErrors           : {}
ProxyAddresses               : {}
SecurityEnabled              : True

You can search for a specific group using the -filter parameter. This parameter takes an ODATA filter clause and returns all groups that match the filter, as in the following example:

PS C:\Windows\system32> Get-AzureADGroup -Filter "DisplayName eq 'Intune Administrators'"


DeletionTimeStamp            :
ObjectId                     : 31f1ff6c-d48c-4f8a-b2e1-abca7fd399df
ObjectType                   : Group
Description                  : Intune Administrators
DirSyncEnabled               :
DisplayName                  : Intune Administrators
LastDirSyncTime              :
Mail                         :
MailEnabled                  : False
MailNickName                 : 4dd067a0-6515-4f23-968a-cc2ffc2eff5c
OnPremisesSecurityIdentifier :
ProvisioningErrors           : {}
ProxyAddresses               : {}
SecurityEnabled              : True

Note

The Azure AD PowerShell cmdlets implement the OData query standard. For more information, see $filter in OData system query options using the OData endpoint.

Create groups

To create a new group in your directory, use the New-AzureADGroup cmdlet. This cmdlet creates a new security group called “Marketing":

PS C:\Windows\system32> New-AzureADGroup -Description "Marketing" -DisplayName "Marketing" -MailEnabled $false -SecurityEnabled $true -MailNickName "Marketing"

Update groups

To update an existing group, use the Set-AzureADGroup cmdlet. In this example, we’re changing the DisplayName property of the group “Intune Administrators.” First, we’re finding the group using the Get-AzureADGroup cmdlet and filter using the DisplayName attribute:

PS C:\Windows\system32> Get-AzureADGroup -Filter "DisplayName eq 'Intune Administrators'"


DeletionTimeStamp            :
ObjectId                     : 31f1ff6c-d48c-4f8a-b2e1-abca7fd399df
ObjectType                   : Group
Description                  : Intune Administrators
DirSyncEnabled               :
DisplayName                  : Intune Administrators
LastDirSyncTime              :
Mail                         :
MailEnabled                  : False
MailNickName                 : 4dd067a0-6515-4f23-968a-cc2ffc2eff5c
OnPremisesSecurityIdentifier :
ProvisioningErrors           : {}
ProxyAddresses               : {}
SecurityEnabled              : True

Next, we’re changing the Description property to the new value “Intune Device Administrators”:

PS C:\Windows\system32> Set-AzureADGroup -ObjectId 31f1ff6c-d48c-4f8a-b2e1-abca7fd399df -Description "Intune Device Administrators"

Now if we find the group again, we see the Description property is updated to reflect the new value:

PS C:\Windows\system32> Get-AzureADGroup -Filter "DisplayName eq 'Intune Administrators'"


DeletionTimeStamp            :
ObjectId                     : 31f1ff6c-d48c-4f8a-b2e1-abca7fd399df
ObjectType                   : Group
Description                  : Intune Device Administrators
DirSyncEnabled               :
DisplayName                  : Intune Administrators
LastDirSyncTime              :
Mail                         :
MailEnabled                  : False
MailNickName                 : 4dd067a0-6515-4f23-968a-cc2ffc2eff5c
OnPremisesSecurityIdentifier :
ProvisioningErrors           : {}
ProxyAddresses               : {}
SecurityEnabled              : True

Delete groups

To delete groups from your directory, use the Remove-AzureADGroup cmdlet as follows:

PS C:\Windows\system32> Remove-AzureADGroup -ObjectId b11ca53e-07cc-455d-9a89-1fe3ab24566b

Manage group membership

Add members

To add new members to a group, use the Add-AzureADGroupMember cmdlet. This command adds a member to the Intune Administrators group we used in the previous example:

PS C:\Windows\system32> Add-AzureADGroupMember -ObjectId 31f1ff6c-d48c-4f8a-b2e1-abca7fd399df -RefObjectId 72cd4bbd-2594-40a2-935c-016f3cfeeeea

The -ObjectId parameter is the ObjectID of the group to which we want to add a member, and the -RefObjectId is the ObjectID of the user we want to add as a member to the group.

Get members

To get the existing members of a group, use the Get-AzureADGroupMember cmdlet, as in this example:

PS C:\Windows\system32> Get-AzureADGroupMember -ObjectId 31f1ff6c-d48c-4f8a-b2e1-abca7fd399df

DeletionTimeStamp ObjectId                             ObjectType
----------------- --------                             ----------
                      72cd4bbd-2594-40a2-935c-016f3cfeeeea User
                      8120cc36-64b4-4080-a9e8-23aa98e8b34f User

Remove members

To remove the member we previously added to the group, use the Remove-AzureADGroupMember cmdlet, as is shown here:

PS C:\Windows\system32> Remove-AzureADGroupMember -ObjectId 31f1ff6c-d48c-4f8a-b2e1-abca7fd399df -MemberId 72cd4bbd-2594-40a2-935c-016f3cfeeeea

Verify members

To verify the group memberships of a user, use the Select-AzureADGroupIdsUserIsMemberOf cmdlet. This cmdlet takes as its parameters the ObjectId of the user for which to check the group memberships, and a list of groups for which to check the memberships. The list of groups must be provided in the form of a complex variable of type “Microsoft.Open.AzureAD.Model.GroupIdsForMembershipCheck”, so we first must create a variable with that type:

PS C:\Windows\system32> $g = new-object Microsoft.Open.AzureAD.Model.GroupIdsForMembershipCheck

Next, we provide values for the groupIds to check in the attribute “GroupIds” of this complex variable:

PS C:\Windows\system32> $g.GroupIds = "b11ca53e-07cc-455d-9a89-1fe3ab24566b", "31f1ff6c-d48c-4f8a-b2e1-abca7fd399df"

Now, if we want to check the group memberships of a user with ObjectID 72cd4bbd-2594-40a2-935c-016f3cfeeeea against the groups in $g, we should use:

PS C:\Windows\system32> Select-AzureADGroupIdsUserIsMemberOf -ObjectId 72cd4bbd-2594-40a2-935c-016f3cfeeeea -GroupIdsForMembershipCheck $g

OdataMetadata                                                                                                 Value
-------------                                                                                                  -----
https://graph.windows.net/85b5ff1e-0402-400c-9e3c-0f9e965325d1/$metadata#Collection(Edm.String)             {31f1ff6c-d48c-4f8a-b2e1-abca7fd399df}

The value returned is a list of groups of which this user is a member. You can also apply this method to check Contacts, Groups or Service Principals membership for a given list of groups, using Select-AzureADGroupIdsContactIsMemberOf, Select-AzureADGroupIdsGroupIsMemberOf or Select-AzureADGroupIdsServicePrincipalIsMemberOf

Disable group creation by your users

You can prevent non-admin users from creating security groups. The default behavior in Microsoft Online Directory Services (MSODS) is to allow non-admin users to create groups, whether or not self-service group management (SSGM) is also enabled. The SSGM setting controls behavior only in the My Apps access panel.

To disable group creation for non-admin users:

  1. Verify that non-admin users are allowed to create groups:

    PS C:\> Get-MsolCompanyInformation | fl UsersPermissionToCreateGroupsEnabled
    
  2. If it returns UsersPermissionToCreateGroupsEnabled : True, then non-admin users can create groups. To disable this feature:

    Set-MsolCompanySettings -UsersPermissionToCreateGroupsEnabled $False
    

Manage owners of groups

To add owners to a group, use the Add-AzureADGroupOwner cmdlet:

PS C:\Windows\system32> Add-AzureADGroupOwner -ObjectId 31f1ff6c-d48c-4f8a-b2e1-abca7fd399df -RefObjectId 72cd4bbd-2594-40a2-935c-016f3cfeeeea

The -ObjectId parameter is the ObjectID of the group to which we want to add an owner, and the -RefObjectId is the ObjectID of the user we want to add as an owner of the group.

To retrieve the owners of a group, use the Get-AzureADGroupOwner cmdlet:

PS C:\Windows\system32> Get-AzureADGroupOwner -ObjectId 31f1ff6c-d48c-4f8a-b2e1-abca7fd399df

The cmdlet returns the list of owners for the specified group:

DeletionTimeStamp ObjectId                             ObjectType
----------------- --------                             ----------
                      e831b3fd-77c9-49c7-9fca-de43e109ef67 User

If you want to remove an owner from a group, use the Remove-AzureADGroupOwner cmdlet:

PS C:\Windows\system32> remove-AzureADGroupOwner -ObjectId 31f1ff6c-d48c-4f8a-b2e1-abca7fd399df -OwnerId e831b3fd-77c9-49c7-9fca-de43e109ef67

Reserved aliases

When a group is created, certain endpoints allow the end user to specify a mailNickname or alias to be used as part of the email address of the group. Groups with the following highly privileged email aliases can only be created by an Azure AD global administrator.

  • abuse
  • admin
  • administrator
  • hostmaster
  • majordomo
  • postmaster
  • root
  • secure
  • security
  • ssl-admin
  • webmaster

Next steps

You can find more Azure Active Directory PowerShell documentation at Azure Active Directory Cmdlets.