Summary

During installation and initial configuration, Cayosoft Administrator performs various pre-installation checks to ensure all required components are installed and system settings are configured properly. However, there is the possibility that some settings may have been updated after the Cayosoft Administrator installation, or some settings were not properly verified during installation. This article provides an extensive set of verification procedures to ensure the system where Cayosoft Administration Service is installed and configured properly.

Applies to: Cayosoft Administrator 7.x or later

ID: 20180503-1

In this article:

Typical error messages

Microsoft 365 connection account password issues

Microsoft 365 connection account issues

Exchange Online connection issues

Microsoft Teams module connection issues

Sharepoint Online connection issues  

Microsoft 365 connection issues

1. Verify Microsoft 365 connection account

1.1 Login to Office Portal with the Microsoft 365 connection account

Requirements 

• Credentials provided for Microsoft 365 connection account must be valid to log on to Microsoft Admin Portal. If there is a prompt to complete a password reset it must be completed.

How to check

1. Open Microsoft 365 Admin Panel and reset the password for Microsoft 365 connection account. Make sure to clear the checkbox Make this user change their password when they first sign in:
   
   
2. Log on to https://portal.office.com with the new password for Microsoft 365 connection account, to make sure these credentials would be valid.
3. Open Cayosoft Administrator Console.
4. Click [...] button next to the account.
5. Specify a new password for Microsoft 365 connection account.
6. Restart Administration Service to make sure all sessions are fully re-established:
   
   

How to check if the account password is set to never expire

You can check and set the account password to never expire if it is not set to it. Microsoft 365 native Admin Center does not provide a user interface for this, so you have 2 options:

1. Do it in PowerShell, as described for examples here: https://support.office.com/en-us/article/set-an-individual-user-s-password-to-never-expire-f493e3af-e1d8-4668-9211-230c245a0466.
2. Do it in Cayosoft Administrator Web UI, after you reset the password and make the Cayosoft Administrator work again. So, after Cayosoft Administrator re-establishes the connection to Microsoft 365:
   1. Open Web UI.
   2. Navigate to Microsoft Microsoft 365 > Users. 
   3. Search for the connection account used to connect to Microsoft 365.
   4. Click Reset Password action.
   5. Check Password never expires.

1.2 Check Microsoft 365 settings in the Cayosoft Administrator Console

Requirements

• Microsoft 365 extension must be enabled.
• Valid Microsoft 365 credentials must be provided as a Microsoft 365 connection account.
• Check Settings and the Run Components Check and resolve any reported errors.

How to check 

1. In the Cayosoft Administrator console, navigate to Microsoft Microsoft 365 Extension.
2. Check the Microsoft 365 credentials are not empty - this is the account being used to connect to Microsoft 365. There are several steps listed below to verify this account is configured properly.
3. Click the Check Settings command from the menu in the right pane and confirm it completes without an error.
   Note: This command validates the specified settings and verifies that:

   1. The account credentials are correct.
   2. Connection account role membership.
   3. Connection to Exchange Online.

   If the Check Settings command completes successfully but you still get the error in Web Portal you should troubleshoot the Exchange Online connection. Please see the step-by-step instructions in sections 1.5 and 1.6.
4. Run the Run Components Check and confirm all required components are installed.
   
   

1.3 Check if Microsoft 365 connection account is a cloud-only account

Requirement

• Microsoft 365 connection account should be a cloud-only account, i.e. an account that is not synchronized with Azure AD Connect.

How to resolve

1. Navigate to https://login.microsoftonline.com.
2. Open Microsoft 365 Admin Center, open the list of Active users, and locate the Microsoft 365 connection account in the list. Make sure the Sync Type column states "In cloud" for the account, as shown on the screenshot below.

1.4 Validate Microsoft 365 connection account for MFA enforcement

Requirement

• Microsoft 365 connection account should be excluded from MFA enforcement.

How to resolve

Starting with version 7.1.0, Cayosoft Administrator can automatically validate the Microsoft 365 connection account and check that the Microsoft 365 connection account is enrolled to MFA, but additional configuration steps are required for Cayosoft Administrator to work correctly in such an environment:

1. In Cayosoft Administrator Console navigate to Home > Configuration > Connected Systems Extensions > Microsoft 365.
2. Click ... button next to Microsoft 365 credentials.
3. On Specify Credentials window click Validate to check that Microsoft 365 connection account is enrolled to MFA.
   
   
   
4. Perform the steps described in these articles:

   1. Check if CAPs affect the Microsoft 365 connection account. 

   2. Check if Security Defaults is enabled and exclude Microsoft 365 connection account from the Security Defaults.

   3. Disable Legacy Multi-Factor Authentication (MFA) for Microsoft 365 Connection account. 

1.5 Verify the Global Administrator role for the Microsoft 365 connection account 

Requirement

• Microsoft 365 connection account must be assigned a Global administrator role in Microsoft 365 (Azure AD). For more details, please see Permissions required for AD and Microsoft 365 accounts used by Cayosoft Administrator article.

How to check

1. In the Microsoft 365 Admin Portal, select the account you intend to use as the connection account for Cayosoft Administrator.
2. Open Roles dialog for the selected account.
3. Make sure the Global administrator role is assigned, as shown in the screenshot below.
   1. See Microsoft KB http://support.microsoft.com/kb/2905767 for details on ensuring the administrative account has Microsoft 365 Administrative Credentials.

1.6 Verify Exchange Online roles for the Microsoft 365 connection account

Requirement 

• Microsoft 365 connection account must be a member of the Organization Management role in Exchange Online.

How to check

1. In the Microsoft 365 Admin Portal, expand the Admin centers navigation group and select Exchange to go to Exchange Admin Center.
2. Select Roles > Admin roles menu item in the Exchange Admin Center.
3. Find the "Organization Management" role group and click the Assigned tab.
4. Make sure the Microsoft 365 connection account is present in the list. If the connection account is a member of the Global Administrators Azure role, the presence of the group 'Company Administrator' in the list is sufficient.

1.7 Verify Organization Management role group in Exchange Online has all default roles enabled

Requirement

Ensure that the Organization Management role group in Exchange Online has all default roles enabled. If you disable some default roles, the Cayosoft Administrator connection account can lose assets to required functions and you'll get errors that some PowerShell commands are not found.

How to check

1. In the Microsoft 365 Admin Portal, expand the Admin Centers navigation group and select Exchange to go to Exchange Admin Center.
2. Select Roles > Admin roles menu item in the Exchange Admin Center.
3. Find the "Organization Management" role group and click the Permissions tab.
4. Make sure that you have all the permissions from the list in this article for the "Organization Management" role group selected.

1.8 Verify Access Control policies are enforced in SharePoint online

How to check

1. Sign in to the Access control page of the SharePoint admin center. 
2. Check Unmanaged devices and Apps that don't use modern authentication policies:
3. If the Unmanaged devices policy is set to anything other than Allow full access, you need to make the computer running Cayosoft Administrator a managed device, i.e. you need to join it to Azure AD.
4. If the Apps that don't use modern authentication is set to Block access you should check that Modern authentication is enabled in Microsoft Microsoft 365 extension in the Cayosoft Admin console.
5. If the error still persists add the registry subkey on the client computer to force modern authentication that will resolve the errors with connection to SharePoint Online. For details please see this article Troubleshooting connection to SharePoint Online – Cayosoft Help Center. 

2. Verify Required Software Components and System Settings

2.1 Verify required Software components

Requirement

• The MSOnline PowerShell for Azure AD, and Exchange Online PowerShell Module components are required for Cayosoft Administrator to connect to and manage Microsoft Azure Active Directory, Microsoft 365, and Exchange Online.

How to check

1. On the system where Administration Service is deployed, run the Cayosoft Requirements Check from the Start menu
2. Make sure both components are marked as <Installed>: MSOnline PowerShell for Azure Active Directory, and Exchange Online PowerShell Module. See the screenshot below.
   
   

3. Test Connection

3.1 Verify PowerShell remoting is enabled

Requirement

• PowerShell Remoting must be enabled.

How to check

1. Click Start (or press the Windows flag key). The windows start menu or start screen should appear.

2. Run PowerShell ISE as administrator.

3. Run the following script:

   Enter-PSSession –computername localhost

4. No warnings or messages should appear, only the command prompt should be visible, as shown in the screenshot below.

How to resolve

If a warning message appears you will need to enable PowerShell Remoting:

Enable-psremoting

3.2 Verify PowerShell Execution Policy is Unrestricted or RemoteSigned

Requirement

• PowerShell Execution Policy must be set to Unrestricted or RemoteSigned.

How to check

1. Run PowerShell ISE as administrator.
2. In the PowerShell ISE Window run the following script:

   get-ExecutionPolicy

A value of Unrestricted or RemoteSigned should be returned, as shown in the screenshot below.

How to resolve

If the system does not return Unrestricted or RemoteSigned then use the following command to set the policy:

set-executionpolicy remotesigned

3.3 Verify Windows Remoting (WINRM) is Enabled

Requirement

• Windows Remoting service must be started.

How to check

1. Run PowerShell ISE as administrator.
2. Run the following script:

   Get-service winrm

3. You should see the message displayed below:

How to resolve

If the system indicates WINRM is not running then run the following command to start the service:

net start winrm 

3.4 Verify Basic Authentication is Enabled for Windows Remoting (WINRM)

Requirement

For versions 9.x and earlier, Basic Authentication must be enabled for Windows Remoting on the machine running the Cayosoft Administrator. This is a Microsoft requirement for Exchange online:
About the Exchange Online PowerShell V2 module and V3 module | Microsoft Learn
 
The 10.1 version and later, Cayosoft Administrator is using the newer EXO module and REST-based commands that do not require Basic authentication in WinRM.

How to check

1. Run PowerShell ISE as administrator.
2. Run the following script:

   winrm get winrm/config/client/auth

3. Check if Basic parameter is set to "true".
   
   
   
   

How to resolve

1. If Basic = false is displayed, then run the following command to enable Basic Authentication:

   winrm set winrm/config/client/auth '@{Basic="true"}' 

   
   
2. If Basic = false [Source = "GPO"] is displayed you should find the Group Policy and disable it then set Basic = true:
   1. Get all available information about Group Policy. It includes detailed settings that were applied with a precedence of 1 and higher:
      

      gpresult /z

   2. When you found the Group Policy, disable it.
   3. Update group policy:

      gpupdate /force

   4. Run the following script to enable Basic Authentication:

      winrm set winrm/config/client/auth '@{Basic="true"}'

3. Restart the Cayosoft Administrator service after changing the settings.

3.5 Test connection to Azure Cloud Services outside of Cayosoft Administrator

To eliminate the possibility that Firewall, Proxy, PowerShell, or other environmental problems are preventing the Cayosoft Administrator to connect to Azure Cloud Services, use PowerShell ISE Window as Administrator to run the scripts below. For each Azure service, use Microsoft 365 connection account that is specified in Cayosoft Administrator Console in Home > Configuration > Connected Systems Extensions > Microsoft 365.

Microsoft 365

[Net.ServicePointManager]::SecurityProtocol=[Net.SecurityProtocolType]::Tls12 -bor [Net.SecurityProtocolType]::Ssl3;
Connect-MsolService 

Exchange Online

Please stop Administrator Service before connecting to Exchange Online to avoid the sessions limit.

Stop-Service CayoAdminService
[Net.ServicePointManager]::SecurityProtocol=[Net.SecurityProtocolType]::Tls12 -bor [Net.SecurityProtocolType]::Ssl3;
Connect-ExchangeOnline 

Microsoft Teams 

[Net.ServicePointManager]::SecurityProtocol=[Net.SecurityProtocolType]::Tls12 -bor [Net.SecurityProtocolType]::Ssl3;
Connect-MicrosoftTeams 

Sharepoint Online

[Net.ServicePointManager]::SecurityProtocol=[Net.SecurityProtocolType]::Tls12 -bor [Net.SecurityProtocolType]::Ssl3;
$credential = Get-Credential 
Connect-SPOService -Url https://contoso-admin.sharepoint.com -Credential $credential 

Cayosoft Graph

[Net.ServicePointManager]::SecurityProtocol=[Net.SecurityProtocolType]::Tls12 -bor [Net.SecurityProtocolType]::Ssl3;
Connect-CGraphAdminService -Server '<Server name>'

3.6 Next Steps

If the connection was successful, but you still experience problems, please contact Cayosoft Support for additional assistance.

If the connection failed please verify that Antivirus, Firewall or Proxy Settings are not preventing this computer from connecting to Microsoft 365.

4. Check Cayosoft Administrator Configuration 

4.1 Verify Microsoft 365 API URL is specified

How to check

1. In Admin Console navigate to Home > Configuration > Connected Systems Extensions > Microsoft 365
2. Open the Advanced Settings section.
3. Check that Microsoft 365 API URL (Advanced) setting has https://outlook.office365.com/powershell-liveid/ value.

How to resolve

If the value is empty, copy\paste this value and save the changes.

5. The maximum number of Exchange Online connections exceeded

You may get the error due to the limitation of the number of sessions to Exchange Online. A maximum of three simultaneous remote PowerShell connections to Exchange Online Organization is allowed. You should wait for 30 minutes, after that the sessions that are not used would be closed and the error won't be displayed. 

Appendix

Resolution for the Data returned by the remote Get-FormatData command is not in the expected format error 

This is a known issue related to Exchange Online sessions introduced by Microsoft. It appears only on some Microsoft 365 tenants. Cayosoft Administrator re-creates Exchange Online sessions on start and then after they are expired. Due to this problem, new Exchange sessions can not be recreated. For more details, please read this post: https://answers.microsoft.com/en-us/msoffice/forum/all/cannot-connect-to-exchange-online-via-powershell/25ca1cc2-e23a-470e-9c73-e6c56c4fbb46?page=5

According to the post, this issue can go away after some time. But in the 7.3.0 version new Apply fix for Get-FormatData error setting was added in the Advanced Settings section in Microsoft Microsift 365 extension:

1. In Admin Console navigate to  Home > Configuration > Connected Systems Extensions > Microsoft Microsoft 365.
2. Expand Advanced Settings section.
3. Set Apply fix for Get-FormatData error to Try 2nd workaround.
4. Click Save Changes.
5. Restart Cayosoft Service.

If the issue still is not resolved, select Try 1st workaround in step 3.