Configuration: Add a Tenant

This article describes how to add a new Microsoft 365 tenant in Cayosoft Guardian. The wizard guides you through the connection method, configuration account, application account creation, service selection, and confirmation. If your tenant is in a Microsoft government cloud, complete Before you add a tenant in a government cloud (GCC) or Before you add a tenant in GCC High first, as applicable.

Prerequisites

• A Microsoft Entra Global Administrator account to grant consent and complete setup.
• Network and browser access to your Microsoft 365 tenant, including the sign-in and consent endpoints for your Microsoft cloud environment.
• Outbound access to every endpoint Cayosoft Guardian uses for your cloud environment, including the consent redirect hosts used to complete admin consent and the unified audit log host. In GCC, Guardian reads the unified audit log from manage-gcc.office.com. In GCC High, Cayosoft Guardian reads the unified audit log from manage.office365.us. For the full list, see Planning and preparation: Required ports for Cayosoft Guardian.
• For a tenant in a government cloud: the Microsoft cloud environment set to GCC or GCC High before you add the tenant. See Before you add a tenant in a government cloud (GCC) or Before you add a tenant in GCC High.

Before you add a tenant in a government cloud (GCC)

Cayosoft Guardian connects to tenants in the Commercial cloud and in GCC. The Microsoft cloud environment is an installation-wide setting: it applies to every tenant, job, and Active Directory agent in the installation. One installation serves either commercial tenants or government tenants, not both.

Set the environment before you add the tenant. If you add the tenant first, Guardian connects to the commercial endpoints and the tenant is added with endpoint errors.

To set the Microsoft cloud environment

1. In the Cayosoft Guardian web portal, go to Service Settings > Authentication Settings.
2. In Microsoft cloud environment, select GCC.
3. Save the change.

NOTE: If you're running the configuration wizard on a new installation, set the environment between Step 2, Configure database and Step 3, Add tenant. Then return to the wizard and continue.

After the environment is set, add the tenant as described in Adding a tenant. Nothing else changes: Guardian connects with the application shipped with the product, and a Global Administrator grants consent in the same way as in a commercial tenant. You don't register or configure an application manually.

NOTE: In GCC, you sign in and grant consent at the standard Microsoft Entra endpoints. The Microsoft 365 service endpoints are what differ — for example, Guardian reads the unified audit log from manage-gcc.office.com.

To verify the tenant connected

1. Go to Configuration > Managed tenants.
2. Confirm that the tenant shows the Success state and reports no endpoint errors.
3. Open the tenant's Entra ID job and confirm that changes are collected.

If the tenant shows endpoint errors, check that Microsoft cloud environment matches your tenant's cloud, and that your firewall or proxy allows the endpoints listed in Planning and preparation: Required ports for Cayosoft Guardian.

Change monitoring in GCC

To perform initiator discovery for Exchange Online and Teams change history Guardian relies on Microsoft 365 Management Activity log (aka Microsoft Purview unified audit logs). When 'Microsoft Cloud Environment' on Authentication Settings is set to 'GCC', Guardian uses API endpoint https://manage-gcc.office.com to access the log. In some cases in GCC tenants the log can be accessed via Global API endpoint https://manage.office.com instead.

If initiator is not populated for Exchange Online changes in your GCC tenant, try switching to Global unified log endpoint:

• Open Change Monitoring > Jobs > Entra Event Collection for the tenant
• In the Workflow steps list, click on Collect Exchange Online Audit Log
• In the Microsoft 365 management activity API endpoint field, enter https://manage.office.com

If you experience issues with initiator population for Teams changes, perform the same steps for the workflow step Collect Microsoft 365 Unified Log.

Standby Forest Recovery in GCC

A standby forest can provision and target Azure resources in a GCC subscription. A GCC tenant's Azure subscription is typically a standard commercial Azure subscription, so no additional endpoints are needed beyond those documented for commercial deployments. See Cloud Services for how to add the Azure subscription used for Forest Recovery.

If the shipped application can't be consented

Some government tenants block consent to applications published outside the tenant. If a Global Administrator can't grant consent to the Cayosoft Guardian application, point the installation at an application registration that you own by editing appsettings.json.

1. In your GCC tenant, register an application and grant it the permissions Guardian needs for the services you plan to monitor. See Permissions for Change Monitoring and Rollback in Cayosoft Guardian.
2. On the Cayosoft Guardian server, stop the Cayosoft Guardian service.
3. Open appsettings.json.
4. Replace the application (client) ID with the ID of your registration, and save the file.
5. Start the Cayosoft Guardian service.
6. Add the tenant as described in Adding a tenant, and grant consent to your own application when prompted.

NOTE: appsettings.json applies to the whole installation. Back up the file before you edit it, keep the JSON valid, and change only the application values. An invalid file prevents the service from starting.

Before you add a tenant in GCC High

GCC High is a separate Microsoft cloud environment from GCC, with its own Microsoft Entra instance, Microsoft Graph, Exchange Online, Azure Resource Manager, Azure Storage, and unified audit log hosts. As with GCC, the Microsoft cloud environment is an installation-wide setting that applies to every tenant, job, and Active Directory agent in the installation, and it must be set before you add the tenant. If your tenant is in GCC rather than GCC High, see Before you add a tenant in a government cloud (GCC) above.

To set the Microsoft cloud environment

1. In the Cayosoft Guardian web portal, go to Service Settings > Authentication Settings.
2. In Microsoft cloud environment, select GCC High.
3. Save the change.

NOTE: Because the sign-in authority is itself cloud-specific, reach Authentication Settings by signing in with Windows integrated authentication before any cloud is configured. Once GCC High is selected, Microsoft 365 sign-in and consent resolve against login.microsoftonline.us instead of the commercial or GCC authority. If you're running the configuration wizard on a new installation, set the environment between Step 2, Configure database and Step 3, Add tenant, then return to the wizard and continue.

After the environment is set, add the tenant as described in Adding a tenant. Guardian connects using the Cayosoft application registered in a Cayosoft-owned GCC High tenant and shipped as the default application for that cloud, and a Global Administrator of your GCC High tenant grants consent in the same way as in a commercial or GCC tenant. The consent flow completes entirely within reach of the GCC High network — it doesn't redirect through commercial-cloud endpoints. You don't register or configure an application manually unless the shipped application can't be consented; see If the shipped application can't be consented above.

GCC High endpoints

When Microsoft cloud environment is set to GCC High, all Guardian service calls resolve to GCC High endpoints instead of commercial or GCC endpoints, including the Entra authority (login.microsoftonline.us), Microsoft Graph (graph.microsoft.us), Exchange Online, Azure Resource Manager, Azure Storage, and the unified audit log (manage.office365.us). For the full list of endpoints and ports — including the endpoints required when a GCC High host monitors a tenant in another Microsoft cloud — see Planning and preparation: Required ports for Cayosoft Guardian.

Limited onboarding scenarios

You can add a GCC High tenant for delegated administrator management alone, with change collection turned off and without any Microsoft 365 workloads present. Workloads that are unavailable in your GCC High tenant don't block tenant onboarding or cause collection failures for the workloads you do monitor.

Change monitoring in GCC High

Entra ID, Exchange Online, and Teams changes are collected with the initiator populated, the same as in commercial and GCC tenants. Guardian reads the unified audit log from manage.office365.us.

Standby Forest Recovery in GCC High

A standby forest can provision and target Azure resources in a GCC High subscription. See Cloud Services for how to add the Azure subscription used for Forest Recovery.

NOTE: Commercial installations behave exactly as they do today, regardless of the government cloud options available in Microsoft cloud environment. Cayosoft Guardian supports Commercial, GCC, and GCC High. The Microsoft 365 DoD cloud isn't currently supported.

Adding a tenant

Adding your Entra ID/Microsoft 365 cloud tenant immediately enables change monitoring and data backup for continuous protection against unwanted changes.

1. Choose how Guardian will connect to Microsoft 365:

   • Create Microsoft Entra application (recommended) – Guardian will create and configure an application in Microsoft Entra ID with the required roles.
   • Use credentials of an existing user account (legacy) – Legacy authentication option using an existing account.

   RECOMMENDED: Use the Microsoft Entra application method for enhanced security and easier management. Learn more: Entra application accounts.

   

2. If you select Create Microsoft Entra application (recommended), the account you sign in with:

   • Must be a member of the Global Administrator role.

   

3. If you select Use credentials of an existing user account (legacy), the account must meet the following requirements:

   • Must be a member of the Global Administrator role.
   • Should be a dedicated account created specifically for Cayosoft Guardian.
   • Must not be synced from on-premises Active Directory.

   

4. Enter the account in the format username@domain.com. This account is used only during configuration and is not preserved.

5. Sign in to your Microsoft Entra tenant so Guardian can automatically create and configure the application and assign the required roles.

   • Sign In with a Global Administrator and grant consent when prompted.
   • Name for Microsoft Entra application – defaults to Cayosoft Guardian service account (you can rename if needed).

   NOTE: In a government cloud installation, confirm that Microsoft cloud environment is set to GCC or GCC High, matching your tenant, before you sign in. If it isn't, the tenant is added against the wrong cloud's endpoints and reports endpoint errors. See Before you add a tenant in a government cloud (GCC) or Before you add a tenant in GCC High.

6. Admin consent must be granted for Guardian to access the tenant. Click Sign In and log in using a Global Administrator account.

7. Enable Grant write permission for automatic rollback.

   NOTE: Enabling this option grants the required write permissions so that Cayosoft Guardian can perform rollback operations when needed. After all rollback tasks are complete, you should manually de-elevate the account to remove write permissions and reduce security risk. For details on managing access, see Managing access .

    

   

8. Choose which Microsoft 365 services Guardian will monitor for changes:

   • Entra ID
   • Exchange Online
   • Teams
   • Intune

   NOTE: Enabling additional services increases database storage requirements. Use the system requirements calculator to estimate storage needs.

   Cayosoft Guardian automatically configures the Microsoft Entra application with the required permissions for the selected services.

   Microsoft Entra application permissions

   When you add a tenant using a Microsoft Entra application, Cayosoft Guardian configures the application with the permissions required for the selected Microsoft 365 services.

   Guardian versions or features introduced after the tenant was initially configured may require additional Microsoft Graph permissions. If Guardian detects that a required permission is missing, update the application permissions and grant administrator consent before using the affected functionality.

   For the complete list of permissions required by Cayosoft Guardian and their purpose, see Permissions for Change Monitoring and Rollback in Cayosoft Guardian.

   Update application permissions

   If additional permissions are required for an existing tenant:

   1. In Cayosoft Guardian, go to Configuration > Managed Tenants.
   2. Select the tenant.
   3. Go to Configuration > Credentials, locate the tenant's Entra ID service account, and open its Properties.
   4. Click Grant access.
   5. Sign in using an account that can grant administrator consent.
   6. Review and accept the requested permissions.
   7. Verify that Cayosoft Guardian no longer reports the permission as missing.

   

   Once configuration is complete, the tenant appears in your list of managed tenants.

9. You will see the following details:

   • Tenant name
   • Configuration account name
   • Guardian service application account
   • Configured jobs (e.g., Entra ID)

   

Managing access

With this feature, Cayosoft Guardian helps your organization follow security best practices while still maintaining rollback and recovery capabilities when required.

To elevate access for Microsoft Entra tenants:

1. In the Cayosoft Guardian web portal, go to Configuration > Managed Tenants.

2. From the tenant list, choose the tenant you want to elevate.

3. At the top of the tenant details pane, click Elevate access.

4. In the Account name field, enter the Global Administrator account in the format: username@domain.com.

5. Click Sign in and complete the authentication process.

6. After signing in, click Elevate to grant write permissions.

7. Confirm that the tenant status reflects elevated access.

   

To de-elevate connection accounts for Microsoft Entra tenants :

1. In the Cayosoft Guardian web portal, go to Configuration > Managed Tenants.

2. From the tenant list, choose the tenant you want to de-elevate.

3. At the top of the tenant details pane, click De-elevate access.

4. In the Account name field, enter the Global Administrator account in the format: username@domain.com

5. Click Sign in and complete the authentication process.

6. After signing in, click De-elevate to remove elevated write permissions.

7. Confirm that the tenant status reflects de-elevated access.

   

Switching tenant connection method

To change a managed tenant from the legacy User account connection to the Microsoft Entra application connection, remove the tenant and add it back using the Entra application account method.

1. In the Guardian web console, go to Configuration > Managed Tenants.
2. Select the tenant you want to switch and choose Delete.
3. After removal completes, select Add tenant.
4. When prompted for the connection method, choose Microsoft Entra application and complete the Add tenant flow.

For more information on how to swith the connection method to gMSA, see Switch existing forest recovery plans to use gMSA in Forest Recovery: Create, configure, verify and run forest recovery plan.

Managing credentials

To edit the credentials:

1. Open the Cayosoft Guardian web portal.
2. Expand Configuration node.
3. Select the Managed tenants node.
4. Select the tenant and click Properties.
5. On the Credentials tab, click Edit.
6. Click Add + and select the credentials to be added.

7. For Token credential, specify:

   • Account name – the account name for which the credential is being configured.
   • Refresh token – the refresh token (or password) associated with the account.
   • Type – the type of token credentials.

8. For Password credential, specify:

   • Account name – the account name for which the credential is being configured.
   • Password – the password associated with the account.
   • Type – the type of password credentials.

To delete the credentials:

1. Open the Cayosoft Guardian web portal.
2. Expand Configuration node.
3. Select the Managed tenants node.
4. Select the tenant and click Properties.
5. On the Credentials tab, click Edit.
6. Click the vertical kebab icon and click Delete.
7. Confirm the deletion.