Overview
Cayosoft Administrator requires a dedicated Entra ID application to work with your Microsoft 365 data using the Microsoft Graph API. When you first set up the Microsoft 365 extension, Cayosoft Administrator registers the Entra ID application in your tenant. The app is used to access, read, and write data. This article covers the steps to register an Entra ID application for your Cayosoft Administrator instance. For additional information permissions required for your Microsoft 365 account used to create the target app, refer to the following article: Permissions required for Active Directory and Microsoft 365 connection accounts.
Requirements
The following items must be configured before you proceed:
-
The Exchange Online PowerShell module must be installed.
-
The Microsoft 365 credentials for the connection account must be provided. Alternatively, you can create a dedicated Microsoft 365 connection account.
NOTE: The PowerShell module can be installed using the Cayosoft Requirements Check tool included in the installation.
Registering an app from the Cayosoft Administrator Console (recommended)
IMPORTANT: When granting permissions, do not select the Consent on behalf of your organization checkbox.
Refer to the following steps to register an Entra ID app from the Cayosoft Administrator Console:
-
In the Cayosoft Administrator Console, navigate to Configuration > Connected Systems Extensions > Microsoft 365 extension settings.
-
Verify that the Microsoft 365 credentials are specified.
-
Click Find or register the app.
-
When requested, specify the password for the service Microsoft 365 account and click Sign in. Review the requested permissions and click Accept. Allow Cayosoft Administrator to create and configure the application.
-
Once the application is created, the Entra ID application consent section expands into a table. The table should contain a Microsoft Graph API entry. Click the Grant Consent button to proceed with the registration.
-
If requested, specify the password for the Microsoft 365 account specified and click Sign in.
-
Review the requested permissions and click Accept.
-
Verity that the consent status switched to Consent fully granted.
Register Entra ID application using PowerShell script
You can install the application using a PowerShell script. To register an application, run the script below.
NOTE: When you run the script, you must specify credentials for the Microsoft 365 connection account.
Set-Variable CayoSoftGraphApiName -option Constant -value "Cayosoft Administrator API Access" # **before v5.4.0 name was "CayosoftGraphApiAccessApp"**
Set-Variable CayoSoftGraphApiRedirectUrlCollection -option Constant -value @("urn:ietf:wg:oauth:2.0:oob")
Import-Module Cayosoft.Graph
$cGraphConnection = Connect-CGraph -SetAsDefaultConnection:$False -Scope "Application.ReadWrite.All"
$app = Get-CGraphResource applications -Filter { displayName -eq $CayoSoftGraphApiName } -Beta -Connection $cGraphConnection
if ($null -ne $app) { Write-Host "API Access app found, exiting."; return }
$requiredAccesses = @(
@{
AppId = "00000003-0000-0000-c000-000000000000"; # Microsoft Graph
Scopes = @(
"AuditLog.Read.All",
"BitLockerKey.Read.All",
"Calendars.ReadWrite.Shared",
"DeviceLocalCredential.Read.All",
"DeviceManagementManagedDevices.PrivilegedOperations.All",
"DeviceManagementManagedDevices.ReadWrite.All",
"Directory.AccessAsUser.All",
"Directory.ReadWrite.All",
"Files.Read.All",
"Group.ReadWrite.All",
"Mail.ReadWrite",
"Mail.ReadWrite.Shared",
"Mail.Send",
"Mail.Send.Shared",
"Member.Read.Hidden",
"Organization.Read.All",
"Policy.ReadWrite.AuthenticationMethod",
"User.Invite.All",
"User.ReadWrite.All",
"UserAuthenticationMethod.ReadWrite.All",
"Reports.Read.All"
);
Type = "Scope";
},
@{
AppId = "00000002-0000-0ff1-ce00-000000000000"; # Office 365 Exchange Online
Scopes = @(
"EWS.AccessAsUser.All"
);
Type = "Scope";
}
)
$msGraphPrincipal = Get-CGraphResource servicePrincipals -Filter {appId -eq "00000003-0000-0000-c000-000000000000"} -Connection $cGraphConnection
$allMsGraphScopes = @{}
$msGraphPrincipal.Oauth2PermissionScopes | ForEach-Object { $allMsGraphScopes[$_.Value] = $_.Id }
$requiredAccessesProp = @()
foreach ($requiredAccess in $requiredAccesses) {
$t = @{
"resourceAppId" = $requiredAccess.AppId;
"resourceAccess" = @()
}
$requiredAccessesProp += $t
$requiredAccess.Scopes | % { $t.resourceAccess += @{ "id" = $allMsGraphScopes[$_]; "type" = $requiredAccess.Type } }
}
$appProperties = @{
"displayName" = $CayoSoftGraphApiName;
"isFallbackPublicClient" = $true;
"signInAudience" = "AzureADMyOrg";
"requiredResourceAccess" = $requiredAccessesProp;
"publicClient" = @{ "redirectUris" = $CayoSoftGraphApiRedirectUrlCollection };
}
$app = New-CGraphResource applications -Properties $appProperties -Connection $cGraphConnection
Disconnect-CGraph -Confirm:$False -Connection $cGraphConnection
IMPORTANT: After you register the Entra ID application, you must grant permissions to the application by clicking Grant Access in the Microsoft 365 extension settings.
Remove Entra ID application using script
The application can be removed by the PowerShell script below.
NOTE: When you run the script, you must specify credentials for the Microsoft 365 connection account.
Set-Variable CayoSoftGraphApiName -option Constant -value "Cayosoft Administrator API Access" # **before v5.4.0 name was "CayosoftGraphApiAccessApp"**
Import-Module Cayosoft.Graph
$cGraphConnection = Connect-CGraph -SetAsDefaultConnection:$False -Scope "Application.ReadWrite.All"
$app = Get-CGraphResource applications -Filter {displayName -eq $CayoSoftGraphApiName} -Connection $cGraphConnection
$sp = $null
if ($null -ne $app) { $sp = Get-CGraphResource servicePrincipals -Filter {appId -eq $app.Id} -Connection $cGraphConnection }
if ($null -ne $sp) { [void](Remove-CGraphResource servicePrincipals -Identifier $sp.Id -Connection $cGraphConnection) }
if ($null -ne $app) { [void](Remove-CGraphResource applications -Identifier $app.Id -Connection $cGraphConnection) }
Disconnect-CGraph -Confirm:$False -Connection $cGraphConnection
Comments
0 comments
Article is closed for comments.