Windows PowerShell to manage Office 365
Windows PowerShell cmdlets to accomplish many Microsoft Office 365 administrative tasks such as user management and domain management. 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.
To begin using the Office 365 cmdlets, you first need to install them. The requirements for installing the Office 365 cmdlets are as follows:
- You can install the cmdlets on a Windows 7 or Windows Server 2008 R2 computer.
- You must have Windows PowerShell and the .NET Framework 3.5.1 enabled.
- You must install the Microsoft Online Services Sign-in Assistant. Download and install one of the following from the Microsoft Download Center:
To install the cmdlets, perform the following steps:
- Download one of the following from the Microsoft Download Center:
- To install the cmdlets, double-click the AdministrationConfig.msi file.The installer adds the program to your Start menu and a shortcut to your desktop.
Run a pilot to test single sign-on before setting it up (optional)
Before adding or converting a domain as a single sign-on domain, you may want to run a pilot. Performing a staged rollout of single sign-on is not currently possible; all users become federated at the same time. However, you can pilot single sign-on with a set of production users from your production Active Directory forest.
Pilot users should thoroughly test various sign-in scenarios to ensure that single sign-on (and the AD FS 2.0 deployment) is correctly configured and ready to be rolled out across the entire organization. To test this, have users access Office 365 services from browsers as well as rich client applications (such as Microsoft Office 2010) in the following environments:
- From a domain-joined computer
- From a non-domain-joined computer inside the corporate network
- From a roaming domain-joined computer outside the corporate network
- From the different operating systems that you use in your company
- From a home computer
- From an Internet kiosk (browser only)
- From a smart phone (for example, a smart phone that uses Microsoft Exchange ActiveSync)
Open the Microsoft Online Services Module and type the following necessary cmdlets.
$cred=Get-Credential. When the cmdlet prompts you for credentials, type your Office 365 administration account credentials.
- View the Help file for a cmdlet by typing the following at the command prompt:
get-help <cmdlet-name> -detailed
- Get a list of cmdlets by typing the following at the command prompt:
Manage users: cmdlets to perform a variety of tasks related to managing users, passwords, and UPNs.
- 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: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:cmdlet is used to create a new user in the Microsoft Online directory. In order to give the user access to services, they must also be assigned a license (using the LicenseAssignment parameter).
- Remove-MsolUser: cmdlet is used to remove a user from the Microsoft Online directory. This cmdlet will delete the user, their licenses, and any other associated data.
- 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: 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: cmdlet is used to change the password of a user. This cmdlet can only be used for users with standard identities.
- Set-MsolUserPrincipalName: cmdlet is used to change the User Principal Name (user ID) 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.
- Set-MsolPasswordPolicy: cmdlet can be used to update the password policy of a specified domain or tenant. Two settings are required, the first is to indicate the length of time that a password remains valid before it must be changed and the second is to indicate the number of days before the password expiration date that will trigger when users will receive their first notification that their password will soon expire.
- Get-MsolPasswordPolicy: cmdlet can be used to retrieve the values associated with the Password Expiry window or Password Expiry Notification window for a tenant or specified domain. When a domain name is specified, it must be a verified domain for the company.
Manage group and role membership: 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.
- 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: cmdlet is used to retrieve groups from Office 365. This cmdlet can be used to return a single group (if ObjectId is passed in), or to search within all groups.
- Get-MsolGroupMember: cmdlet is used to retrieve members of the specified group. The members can be either users or groups.
- New-MsolGroup: cmdlet is used to add a new security group to the Microsoft Online directory.
- Remove-MsolGroup: cmdlet is used to delete a group from the Microsoft Online directory.
- 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: cmdlet is used to update the properties of a security group.
- 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: cmdlet can be used to retrieve a list of administrator roles.
- 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: cmdlet is used to retrieve all members of the specified role.
- Remove-MsolRoleMember: cmdlet is used to remove a user from an administrator role.
Manage service principals: cmdlets to perform a variety of tasks related to service principals.
- Set-MsolServicePrincipal:cmdlet updates a service principal in the Microsoft Online directory. 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: 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 the Microsoft Online directory as “service principal” objects. Adding a new application as a service principal allows that application to authenticate to other services such as Microsoft Office 365.
- Get-MsolServicePrincipal: cmdlet can be used to retrieve a service principal or a list of service principals from the Microsoft Online directory.
- Remove-MsolServicePrincipal: cmdlet removes a service principal from the Microsoft Online directory.
- New-MsolServicePrincipalAddress: cmdlet creates a new service principal address object that can be used to update the addresses for a service principal.
- Get-MsolServicePrincipalCredential: cmdlet can be used to retrieve a list of credentials associated with a service principal.
- 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: 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.
Manage domains: cmdlets to perform a variety of domain management tasks, including creating or removing a domain.
- 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 Add-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:cmdlet is used to retrieve company domains.
- Get-MsolDomainVerificationDns: cmdlet is used to return the DNS records that need to be set to verify a domain.
- 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: cmdlet is used to delete a domain from the Microsoft Online directory. The domain being deleted must be empty; that is, there cannot be any users or groups with email addresses in this domain.
- 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: cmdlet is used to change the domain authentication between standard identity and single sign-on. This cmdlet will only update the settings in Office 365; typically the Convert-MsolDomainToStandard or Convert-MsolDomainToFederated should be used instead.
Manage Single sign-on: 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 Office 365.
- New-MsolFederatedDomain: cmdlet adds a new single sign-on domain (also known as identity-federated domain) to Office 365 and configures the relying party trust settings between the on-premises Active Directory Federation Services 2.0 server and Office 365. 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: 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 Office 365. 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 Office 365.
- 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 Office 365. 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: cmdlet gets key settings from both the Active Directory Federation Services 2.0 server and Office 365. You can use this information to troubleshoot authentication problems caused by mismatched settings between the Active Directory Federation Services 2.0 server and Office 365.
- Get-MsolDomainFederationSettings: cmdlet gets key settings from Office 365. Use the Get-MsolFederationProperty cmdlet to get settings for both Office 365 and the Active Directory Federation Services server.
- Remove-MsolFederatedDomain: cmdlet removes the specified single sign-on domain from Office 365 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: cmdlet is used to update the settings of a single sign-on domain.
- Set-MsolADFSContext: cmdlet sets the credentials to connect to Office 365 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: cmdlet changes settings in both the Active Directory Federation Services 2.0 server and Office 365. 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 Office 365. To confirm that the information in the two systems is correct, the Get-MsolFederationProperty cmdlet can be used to retrieve the settings.
Manage Subscription and licenses: cmdlets to manage subscriptions, accounts, and licenses.
- 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: cmdlet will return all the SKUs that the company owns.
- 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: 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.
Manage Company information and services: cmdlets to perform tasks related to managing your company’s information and connecting to Microsoft Office 365 for enterprises.
- Connect-MsolService: cmdlet will attempt to initiate a connection to Office 365. The caller must either provide their credential (a PSCredential object), or use the UseCurrentCredential option if the current logged in user is federated with Office 365. This cmdlet may return a warning or error if the version of the module being used is out of date.
- Set-MsolDirSyncEnabled: cmdlet is used to turn directory synchronization on or off for a company.
- 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: cmdlet is used to retrieve partner-specific information. This cmdlet should only be used for partner tenants.
- 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: cmdlet is used to delete a contact from the Microsoft Online directory.
- Get-MsolCompanyInformation: cmdlet will retrieve company-level information.
- Set-MsolCompanyContactInformation: cmdlet is used to set company-level contact preferences. This includes email addresses for billing, marketing, and technical notifications about Office 365.
- Set-MsolCompanySettings: cmdlet is used to set company-level configuration settings.
- Redo-MsolProvisionContact: cmdlet can be used to retry the provisioning of a contact object in the Microsoft Online directory when a previous attempt to create the contact object resulted in an error.
- Redo-MsolProvisionGroup: cmdlet can be used to retry the provisioning of a group object in the Microsoft Online directory when a previous attempt to create the group object resulted in an error.
- Redo-MsolProvisionUser: cmdlet can be used to retry the provisioning of a user object in the Microsoft Online directory when a previous attempt to create the user object resulted in an error.