UserLock Documentation
UserLock Documentation
You are here: Use cases > Implement Single Sign-On > Advanced > Microsoft 365 PowerShell Commands

Microsoft 365 PowerShell Commands

Microsoft 365 and Azure AD can be managed entirely using Powershell. This document contains several very useful cmdlets regarding domain federation and Single Sign-On.

The MSOnline module - which is necessary for these cmdlets - is installed when the Microsoft 365 configuration tool is launched for the first time.

Connect to Microsoft 365 services

The credentials must be Microsoft 365 Global Administrator credentials.

$creds = Get-Credential
Connect-MsolService -Credential $creds

Domain Federation

Display domain settings

Get-MsolDomain -DomainName domain.com

Display domain federation settings

Get-MsolDomainFederationSettings -DomainName domain.com

Federate a domain with UserLock SSO

  1. Get the signing certificate data: https://<userlockssourl>/api/infos/certificate or download it from the Userlock console: Single-sign on -> Configuration tab -> Download Saml certificate in the Quick Access panel.
  2. Store them in a Powershell variable $certData = "MIICrDCCAZSgAwIBAgI...4Dc6EKzvrg=="
  3. Use the following command Set-MsolDomainAuthentication -DomainName domain.com -Authentication Federated -PassiveLogOnUri https://<userlockssourl>/saml/sso -SigningCertificate $certData -IssuerUri https//<userlockssourl> -PreferredAuthenticationProtocol Samlp -LogOffUri https://<userlockssourl>/connect/endsession

Cancel federation

Set-MsolDomainAuthentication -DomainName domain.com -Authentication Managed

Users Management

Display a user information

To display an Microsoft 365 user properties, it is possible to use the Get-MsolUser cmdlet:
Get-MsolUser -UserPrincipalName user@office365domain.onmicrosoft.com

To display all properties, add the Format-List * command: Get-MsolUser -UserPrincipalName user@office365domain.onmicrosoft.com | Format-List *

Synchronize a user

Deactivate Azure AD Connect

First of all, if Azure AD Connect is running, you need to deactivate it as none of the following operations will be allowed in this case.

To deactivate temporarily Azure AD Connect, you can run the following command: Set-MsolDirSyncEnabled -EnableDirSync $false

To reactivate Azure AD Connect synchronization, please run the following command: Set-MsolDirSyncEnabled -EnableDirSync $true

The ImmutableId

To allow a user to connect to Microsoft 365 with his AD credentials, it is necessary to synchronize its ImmutableID. This property is shared between the local (AD) user and Microsoft 365 (Azure AD) user.

While called ImmutableId in Azure AD, the local (AD) property is the user objectGUID. Both properties must match to make Azure AD recognize an AD user. So, before synchronizing the ImmutableId, it is necessary to retrieve the list of local objectGUIDs for the AD users. To achieve this, please execute the following steps:

  1. Open a cmd prompt
  2. Run the following command: ldifde -f C:\Temp\ImmutableIds.txt -l
    "userPrincipalName,samAccountName,proxyAddresses,objectGUID,mail" -r "(&(objectCategory=person)(objectClass=User)(givenname=*))"

Note: you may need to create the Temp folder in C: drive or change the path of the output file in the above command.

When a user does not exist in Azure AD yet

If the user does not exist yet, it can be created using the Msol-NewUser cmdlet. However, if the target domain is already federated, it is not possible to create the user directly inside it.
It is first necessary to create it in the default domain with the ImmutableId before moving it to the federated domain.

Default domain ends with onmicrosoft.com. Example: office365domain.onmicrosoft.com
Federated domain is the domain of your users email addresses. Example: domain.com.

  1. Search for the ImmutableId of the AD user in the ImmutableIds.txt file (objectGUID property)
  2. Create the user in the default domain (xxx.onmicrosoft.com) New-MsolUser -DisplayName 'New User' -UserPrincipalName newuser@office365domain.onmicrosoft.com -ImmutableId 'immutableId' -Password 'a useless password'
  3. Move the user in the federated domain: Set-MsolUserPrincipalUserName -UserPrincipalName newuser@office365domain.onmicrosoft.com -NewUserPrincipalName newuser@domain.com

Note 1: It is not possible to assign an ImmutableId to a user in a federated domain. Hence the step in the default domain, even for a user creation

Note 2: the password will never be used since once the user will be in the federated domain, the AD credentials will be used

When the user already exists in Azure AD

As the user already exists, it is not possible to use the New-MsolUser cmdlet. However, you can use the Set-MsolUser cmdlet to assign the ImmutableId. First of all, please verify that the ImmutableId is invalid by displaying the user properties (see above). Compare the ImmutableId property with the local objectGUID. If both match, there is nothing to do as the user is already correctly synchronized.

As it is not possible to assign an ImmutableId to a user in a federated domain, it is first necessary to move the user in the default domain. Then, the Set-MsolUser cmdlet will be usable to update the ImmutableId property with the objectGUID found in the ImmutableIds.txt. Finally, the user will be moved back to the federated domain.

  1. Move the user to the default domain:
    Set-MsolUserPrincipalUserName -UserPrincipalName user@domain.com -NewUserPrincipalName user@office365domain.onmicrosoft.com
  2. Update the ImmutableId:
    Set-MsolUser -UserPrincipalName user@office365domain.onmicrosoft.com -ImmutableId UserImmutableId
  3. Move the user back to the federated domain:
    Set-MsolUserPrincipalUserName -UserPrincipalName user@office365domain.onmicrosoft.com -NewUserPrincipalName user@domain.com

Change a password (Azure AD DS only)

It is not possible to change the password of a federated account, so it's necessary to set the user in the default domain, change the password and then set the user back in the federated domain.

  1. Set the user back in the default domain (xxx.onmicrosoft.com) Set-MsolUserPrincipalUserName -UserPrincipalName user@domain.com -NewUserPrincipalName user@office365domain.onmicrosoft.com
  2. Ask the user to connect to so that he can change his password
  3. When the password is changed, set the user back in the federated domain: Set-MsolUserPrincipalUserName -UserPrincipalName newuser@office365domain.onmicrosoft.com -NewUserPrincipalName newuser@domain.com

Unlock an account (Azure AD DS only)

Unlocking an account is not possible using Azure AD DS.