Export (0) Print
Expand All
Expand Minimize

Manage Azure AD using Windows PowerShell

Published: March 22, 2013

Updated: May 9, 2014

Applies To: Azure, Office 365, Windows Intune

noteNote
  • When linking to this page, use http://aka.ms/aadposh.

  • To comment on this content or ask questions about the information presented here, please use our Feedback guidance.

  • This topic provides online help content for cloud services, such as Windows Intune and Office 365, which rely on Microsoft Azure Active Directory for identity and directory services.

  • The Microsoft Azure Active Directory Module for Windows PowerShell cmdlets were previously known as the Microsoft Online Services Module for Windows PowerShell cmdlets.

As an administrator, you can use the Azure Active Directory Module for Windows PowerShell cmdlets to accomplish many Azure AD tenant-based administrative tasks such as user management, domain management and for configuring single sign-on. This topic includes information about how to install these cmdlets for use with your tenant.

The following are required in order to run the Microsoft Azure Active Directory Module:

  • Operating system: Use Windows 7, Windows 8, Windows Server 2008 R2, or Windows Server 2012 with the default version of Microsoft .NET Framework and Windows PowerShell.

  • Install Updates: Ensure you have installed all of the required updates required by the Microsoft cloud services to which you have subscribed. For example, some cloud service features may not work properly without the appropriate versions of operating systems, web browsers, and software.

  • Install Microsoft Online Services Sign-in Assistant: You must install the appropriate version of the Microsoft Online Services Sign-in Assistant for your operating system from the Microsoft Download Center. Microsoft Online Services Sign-In Assistant for IT Professionals RTW.

Return to Contents

You must install the appropriate version of the Azure AD Module for Windows PowerShell for your operating system from the Microsoft Download Center:

After you click the link, click Run to run the installer package:

ImportantImportant
If you are using Windows PowerShell 2.0 and Single Sign-On, you must use at least Windows PowerShell 2.0, and you must have administrator privileges on the AD FS server. Using remote access to the AD FS server is recommended when you run these cmdlets. To do so, you can use Windows PowerShell remoting. For information, see About_Remote_Requirements.

The Set-MsolUser cmdlet includes a StrongAuthenticationRequirements parameter that is required to enable multifactor authentication. If the Set-MsolUser cmdlet in your existing installation does not include a StrongAuthenticationRequirements parameter, re-install the Azure AD Module using either of the preceding links to ensure you are using the most up-to-date version.

If you try to install the Azure AD Module on a computer that has it already installed, you need to remove the existing version before the installation can continue. Use Add/Remove Programs in Control Panel to remove Azure Active Directory Module for Windows PowerShell, or if you have an older installation, to remove Microsoft Online Services Module for Windows PowerShell. Uninstalling removes both the MSOnline and MSOnlineExtended modules.

The Remove-Module cmdlet removes the MSOnline cmdlets from the session but it does not uninstall the module.

Click the Microsoft Azure Active Directory Module for Windows PowerShell shortcut to open a Windows PowerShell workspace that has the cmdlets. Alternatively, you can load the cmdlets manually by typing import-module MSOnline at the Windows PowerShell command prompt.

Before you can run any of the cmdlets discussed in this article, you must first connect to your online service. To do so, run the cmdlet connect-msolservice at the Windows PowerShell command prompt. You will then be prompted for your credentials. If you want, you can supply your credentials in advance, for example:

$msolcred = get-credential
connect-msolservice -credential $msolcred

The first command prompts for credentials and stores them as $msolcred. The next command uses those credentials as $msolcred to connect to the service.

For more information about the Microsoft Azure Active Directory Module for Windows PowerShell cmdlets, you can do the following:

  • To create a folder for help, list the cmdlets, and then open the file in notepad, you can run the following commands at the Windows PowerShell command prompt:

    new-item c:\MSOLHelp -type directory
    get-command | Where-Object {$_.name -like "*msol*"} | format-list | Out-File c:\MSOLHelp\msolcmdlets.txt
    notepad c:\MSOLHelp\msolcmdlets.txt
    
    
  • View the examples for a cmdlet, run the following command at the Windows PowerShell command prompt: get-help <cmdlet-name> -examples

  • View the name, synopsis, description, parameter descriptions, and any examples provided for a cmdlet, run the following command at the Windows PowerShell command prompt: get-help <cmdlet-name> -detailed

  • View the name, synopsis, description, detailed parameters, and any examples provided for a cmdlet, run the following command at the Windows PowerShell command prompt: get-help <cmdlet-name> -full

Return to Contents

Use the following cmdlets to perform a variety of tasks related to managing users, passwords, and UPNs.

 

Windows PowerShell cmdlet Description

Convert-MsolFederatedUser

The Convert-MsolFederatedUser cmdlet is used to update a user in a domain that was recently converted from single sign-on (also known as identity federation) to standard authentication type. A new password must be provided for the user.

Get-MsolUser

The Get-MsolUser cmdlet can be used to retrieve an individual user, or list of users. An individual user will be retrieved if the ObjectId or UserPrincipalName parameter is used.

New-MsolUser

The New-MsolUser cmdlet is used to create a new user in Azure AD. In order to give the user access to services, they must also be assigned a license (using the LicenseAssignment parameter).

Remove-MsolUser

The Remove-MsolUser cmdlet is used to remove a user from Azure AD. This cmdlet will delete the user, their licenses, and any other associated data.

Restore-MsolUser

The Restore-MsolUser cmdlet restores a user that is in the Deleted users view to their original state. Users will remain in the Deleted users view for 30 days.

Set-MsolUser

The Set-MsolUser cmdlet is used to update a user object. Note that this cmdlet should be used for basic properties only. The licenses, password, and User Principal Name for a user can be updated through Set-MsolUserLicense, Set-MsolUserPassword and Set-MsolUserPrincipalName cmdlets respectively.

Set-MsolUserPassword

The Set-MsolUserPassword cmdlet is used to change the password of a user. This cmdlet can only be used for users with standard identities.

Set-MsolUserPrincipalName

The Set-MsolUserPrincipalName cmdlet is used to change the User Principal Name () of a user. This cmdlet can be used to move a user between a federated and standard domain, which will result in their authentication type changing to that of the target domain.

Redo-MsolProvisionUser

The Redo-MsolProvisionUser cmdlet can be used to retry the provisioning of a user object in Azure Active Directory when a previous attempt to create the user object resulted in a validation error.

Return to Contents

Use the following cmdlets to perform a variety of tasks related to group and role membership, including adding a user to a role or group, creating groups, and removing groups.

 

Windows PowerShell cmdlet Description

Add-MsolGroupMember

The Add-MsolGroupMember cmdlet is used to add members to a security group. The new members can be either users or other security groups.

Get-MsolGroup

The Get-MsolGroup cmdlet is used to retrieve groups from Azure AD. This cmdlet can be used to return a single group (if ObjectId is passed in), or to search within all groups.

Get-MsolGroupMember

The Get-MsolGroupMember cmdlet is used to retrieve members of the specified group. The members can be either users or groups.

New-MsolGroup

The New-MsolGroup cmdlet is used to add a new security group to Azure AD.

Remove-MsolGroup

The Remove-MsolGroup cmdlet is used to delete a group from Azure AD.

Remove-MsolGroupMember

The Remove-MsolGroupMember cmdlet is used to remove a member from a security group. This member can be either a user or a group.

Set-MsolGroup

The Set-MsolGroup cmdlet is used to update the properties of a security group.

Add-MsolRoleMember

The Add-MsolRoleMember cmdlet is used to add a member to a role. Currently, only users can be added to a role (adding a security group is not supported).

Get-MsolRole

The Get-MsolRole cmdlet can be used to retrieve a list of administrator roles.

Get-MsolUserRole

The Get-MsolUserRole cmdlet is used to retrieve all of the administrator roles that the specified user belongs to. This cmdlet will also return roles that the user is a member of through security group membership.

Get-MsolRoleMember

The Get-MsolRoleMember cmdlet is used to retrieve all members of the specified role.

Remove-MsolRoleMember

The Remove-MsolRoleMember cmdlet is used to remove a user from an administrator role.

Redo-MsolProvisionGroup

The Redo-MsolProvisionGroup cmdlet can be used to retry the provisioning of a group object in Azure Active Directory when a previous attempt to create the group object resulted in a validation error.

Return to Contents

Use the following cmdlets to perform a variety of tasks related to service principals.

 

Windows PowerShell cmdlet Description

Set-MsolServicePrincipal

The Set-MsolServicePrincipal cmdlet updates a service principal in Azure AD. It can be used to update the display name, enable/disable the service principal, trusted for delegation, the service principal names (SPNs) or the addresses.

New-MsolServicePrincipal

The New-MsolServicePrincipal cmdlet creates a service principal that can be used to represent a Line Of Business (LOB) application or an on-premises server such as Microsoft Exchange, SharePoint or Lync in Azure AD as "service principal" objects. Adding a new application as a service principal allows that application to authenticate to other Microsoft Online Services.

Get-MsolServicePrincipal

The Get-MsolServicePrincipal cmdlet can be used to retrieve a service principal or a list of service principals from Azure AD.

Remove-MsolServicePrincipal

The Remove-MsolServicePrincipal cmdlet removes a service principal from Azure AD.

New-MsolServicePrincipalAddresses

The New-MsolServicePrincipalAddress cmdlet creates a new service principal address object that can be used to update the addresses for a service principal.

Get-MsolServicePrincipalCredential

The Get-MsolServicePrincipalCredential cmdlet can be used to retrieve a list of credentials associated with a service principal.

New-MsolServicePrincipalCredential

The New-MsolServicePrincipalCredential cmdlet can be used to add a new credential to a service principal or to add or roll credential keys for an application. The service principal is identified by supplying either the object ID, application ID, or service principal name (SPN).

Remove-MsolServicePrincipalCredential

The Remove-MsolServicePrincipalCredential cmdlet can be used to remove a credential key from a service principal in the case of a compromise or as part of credential key rollover expiration. The service principal is identified by supplying either the object ID, application ID, or service principal name (SPN). The credential to be removed is identified by its key ID.

Return to Contents

Use the following cmdlets to perform a variety of domain management tasks, including creating or removing a domain.

 

Windows PowerShell cmdlet Description

Confirm-MsolDomain

The Confirm-MsolDomain cmdlet is used to confirm ownership of a domain. In order to confirm ownership, a custom TXT DNS record must be added for the domain. The domain must first be added using the New-MsolDomain cmdlet, and then the Get-MsolDomainVerificationDNS cmdlet should be called to retrieve the details of the DNS record that must be set.Note that there may be a delay (15 to 60 minutes) between when the DNS update is made and when the cmdlet is able to confirm ownership of a domain.

Get-MsolDomain

The Get-MsolDomain cmdlet is used to retrieve company domains.

Get-MsolDomainVerificationDns

The Get-MsolDomainVerificationDns cmdlet is used to return the DNS records that need to be set to verify a domain.

New-MsolDomain

The New-MsolDomain cmdlet is used to create a new domain object. This cmdlet can be used to create a domain with managed or federated identities, although the New-MsolFederatedDomain cmdlet should be used for federated domains in order to ensure proper setup.

Remove-MsolDomain

The Remove-MsolDomain cmdlet is used to delete a domain from Azure AD. The domain being deleted must be empty; that is, there cannot be any users or groups with email addresses in this domain.

Set-MsolDomain

The Set-MsolDomain cmdlet is used to update settings for a domain. Using this cmdlet, the default domain can be changed, or the capabilities (Email, Sharepoint, OfficeCommunicationsOnline) can be changed.

Set-MsolDomainAuthentication

The Set-MsolDomainAuthentication cmdlet is used to change the domain authentication between standard identity and single sign-on. This cmdlet will only update the settings in Azure AD; typically the Convert-MsolDomainToStandard or Convert-MsolDomainToFederated should be used instead.

Get-MsolPasswordPolicy

Retrieves the current password policy for the tenant or the specified domain.

Set-MsolPasswordPolicy

Sets the values associated with the password notification window and password validity window for a specified domain or all domains in the tenant.

Return to Contents

Use the following cmdlets to perform tasks related to single sign-on, such as adding a new single sign-on domain (also known as identity-federated domain) to Azure AD.

 

Windows PowerShell cmdlet Description

New-MsolFederatedDomain

The New-MsolFederatedDomain cmdlet adds a new single sign-on domain (also known as identity-federated domain) to Azure AD and configures the relying party trust settings between the on-premises Active Directory Federation Services 2.0 server and Azure AD. Due to domain verification requirements, you may need to run this cmdlet several times in order to complete the process of adding the new single sign-on domain.

Convert-MsolDomainToStandard

The Convert-MsolDomainToStandard cmdlet converts the specified domain from single sign-on (also known as identity federation) to standard authentication. This process also removes the relying party trust settings in the Active Directory Federation Services 2.0 server and Azure AD. After the conversion, this cmdlet will convert all existing users from single sign-on to standard authentication. Any existing user who was configured for single sign-on will be given a new temporary password as part of the conversion process. Each converted user name and new temporary password will be recorded in a file for reference by the administrator. The administrator can then distribute the new temporary password to each converted user to enable the user to sign in to the cloud service.

Convert-MsolDomainToFederated

The Convert-MsolDomainToFederated cmdlet converts the specified domain from standard authentication to single sign-on (also known as identity federation), including configuring the relying party trust settings between the Active Directory Federation Services 2.0 server and Azure AD. As part of converting a domain from standard authentication to single sign-on, each user must also be converted. This conversion happens automatically the next time a user signs in; no action is required by the administrator.

Get-MsolFederationProperty

The Get-MsolFederationProperty cmdlet gets key settings from both the Active Directory Federation Services 2.0 server and Azure AD. You can use this information to troubleshoot authentication problems caused by mismatched settings between the Active Directory Federation Services 2.0 server and Azure AD.

Get-MsolDomainFederationSettings

The Get-MsolDomainFederationSettings cmdlet gets key settings from Azure AD. Use the Get-MsolFederationProperty cmdlet to get settings for both Azure AD and the Active Directory Federation Services server.

Remove-MsolFederatedDomain

The Remove-MsolFederatedDomain cmdlet removes the specified single sign-on domain from Azure AD and the associated relying party trust settings in Active Directory Federation Services 2.0. Note: If the domain specified has objects associated with it, you will not be able to remove the domain.

Set-MsolDomainFederationSettings

The Set-MsolDomainFederationSettings cmdlet is used to update the settings of a single sign-on domain.

Set-MsolADFSContext

The Set-MsolADFSContext cmdlet sets the credentials to connect to Azure AD and to the Active Directory Federation Services 2.0 (AD FS 2.0) server. This cmdlet must be run before making other single sign-on (also known as identity federation) cmdlet calls. If this cmdlet is called without parameters, the user will be prompted for credentials to connect to the different systems. When the AD FS 2.0 server is used remotely, the user must specify the computer name of the primary AD FS 2.0 server. Note that the specified logfile is shared by all single sign-on cmdlets for the session. A default logfile is created if one is not specified.

Update-MsolFederatedDomain

The Update-MsolFederatedDomain cmdlet changes settings in both the Active Directory Federation Services 2.0 server and Azure AD. It is necessary to run this cmdlet whenever the URLs or certificate information within Active Directory Federation Services 2.0 change due to configuration changes or through regular maintenance of the certificates, such as when a certificate is about to expire. This cmdlet should also be run when changes occur in Azure AD. To confirm that the information in the two systems is correct, the Get-MsolFederationProperty cmdlet can be used to retrieve the settings.

Return to Contents

Use the following cmdlets to manage subscriptions, accounts, and licenses.

 

Windows PowerShell cmdlet Description

Get-MsolSubscription

The Get-MsolSubscription cmdlet returns all the subscriptions that the company has purchased. When assigning licenses to users, the Get-MsolAccountSku API should be used instead.

Get-MsolAccountSku

The Get-MsolAccountSku will return all the SKUs that the company owns.

New-MsolLicenseOptions

The New-MsolLicenseOptions cmdlet creates a new License Options object. This cmdlet disables specific service plans when assigning a user a license using the Add-MsolUser and Set-MsolUserLicense cmdlets.

Set-MsolUserLicense

The Set-MsolUserLicense cmdlet can be used to adjust the licenses for a user. This can include adding a new license, removing a license, updating the license options, or any combination of these actions.

Return to Contents

Use the following cmdlets to perform tasks related to managing your company’s information and connecting to a Microsoft cloud service. There are also cmdlets for tasks performed by partner companies.

 

Windows PowerShell cmdlet Description

Connect-MsolService

The Connect-MsolService cmdlet will attempt to initiate a connection to Azure AD. The caller must either provide their credential (a PSCredential object), or use the UseCurrentCredential option if the current logged in user is federated with Azure AD. This cmdlet may return a warning or error if the version of the module being used is out of date.

Set-MsolDirSyncEnabled

The Set-MsolDirSyncEnabled cmdlet is used to turn directory synchronization on or off for a company.

Get-MsolPartnerContract

The Get-MsolPartnerContract cmdlet should only be used by partners, as it is used to retrieve a list of contracts for a partner. The input to this cmdlet should be a domain to look up, which must be verified for the tenant. If the company exists and the partner has access to this company, then the corresponding contract will be returned.

Get-MsolPartnerInformation

The Get-MsolPartnerInformation cmdlet is used to retrieve partner-specific information. This cmdlet should only be used for partner tenants.

Set-MsolPartnerInformation

The Set-MsolPartnerInformation cmdlet is used by partners to set partner-specific properties. These properties will be viewable by all tenants that the partner has access to.

Get-MsolContact

The Get-MsolContact cmdlet can be used to retrieve a contact object, or list of contacts. A single contact will be retrieved if the ObjectId parameter is used.

Remove-MsolContact

The Remove-MsolContact cmdlet is used to delete a contact from Azure AD.

Redo-MsolProvisionContact

The Redo-MsolProvisionContact cmdlet can be used to retry the provisioning of a contact object in Azure Active Directory when a previous attempt to create the contact object resulted in a validation error.

Get-MsolCompanyInformation

The Get-MsolCompanyInformation cmdlet will retrieve company-level information.

Set-MsolCompanyContactInformation

The Set-MsolCompanyContactInformation cmdlet is used to set company-level contact preferences. This includes email addresses for billing, marketing, and technical notifications about the cloud service.

Set-MsolCompanySettings

The Set-MsolCompanySettings cmdlet is used to set company-level configuration settings.

Add-MsolForeignGroupToRole

Adds the specified group from a partner tenant to a Role in this tenant.

Return to Contents

Windows PowerShell is a task-based command-line shell and scripting language designed for system administration. Unlike most shells, which accept and return text, Windows PowerShell is built on top of the Microsoft .NET Framework common language runtime (CLR) and the .NET Framework, and accepts and returns .NET Framework objects. Windows PowerShell introduces the concept of a cmdlet (pronounced "command-let"), a simple, single-function command-line tool built into the shell. Cmdlets have the following naming convention: a verb and noun separated by a dash (-), such as Get-Help, Get-Process, and Start-Service. Windows PowerShell includes more than one hundred basic core cmdlets. For more information about Windows PowerShell, see the Windows PowerShell Getting Started Guide.

Return to Contents

There are several other places you can get more information and help. These include:

See Also

Was this page helpful?
(1500 characters remaining)
Thank you for your feedback

Community Additions

ADD
Show:
© 2014 Microsoft