Register Adaxes as an app in Entra ID

1. On the app Overview page in the Entra admin center, click Manifest.

2. Locate the requiredResourceAccess key in the manifest.

3. Set the key to the following value.

"requiredResourceAccess": [
    {
        "resourceAppId": "00000003-0000-0000-c000-000000000000",
        "resourceAccess": [
            {
                "id": "9a5d68dd-52b0-4cc2-bd40-abcf44ac3a30",
                "type": "Role"
            },
            {
                "id": "b0afded3-3588-46d8-8b3d-9842eff778da",
                "type": "Role"
            },
            {
                "id": "9241abd9-d0e6-425a-bd4f-47ba86e767a4",
                "type": "Role"
            },
            {
                "id": "62a82d76-70ea-41e2-9197-370581804d09",
                "type": "Role"
            },
            {
                "id": "5facf0c1-8979-4e95-abcf-ff3d079771c0",
                "type": "Role"
            },
            {
                "id": "9e3f62cf-ca93-4989-b6ce-bf83c28f9fe8",
                "type": "Role"
            },
            {
                "id": "9492366f-7969-46a4-8d15-ed1a20078fff",
                "type": "Role"
            },
            {
                "id": "cc117bb9-00cf-4eb8-b580-ea2a878fe8f7",
                "type": "Role"
            },
            {
                "id": "3011c876-62b7-4ada-afa2-506cbbecc68c",
                "type": "Role"
            },
            {
                "id": "741f803b-c850-494e-b5df-cde7c675a1ca",
                "type": "Role"
            },
            {
                "id": "50483e42-d915-4231-9639-7fdb7fd190e5",
                "type": "Role"
            }
        ]
    },
    {
        "resourceAppId": "00000002-0000-0ff1-ce00-000000000000",
        "resourceAccess": [
            {
                "id": "dc50a0fb-09a3-484d-be87-e023b12c6440",
                "type": "Role"
            },
            {
                "id": "7146a1f0-8703-45b3-9eae-527a64c00995",
                "type": "Role"
            }
        ]
    }
]

4. Click Save.

5. Click API permissions.

6. Verify that the list contains the required permissions.

The script registers an app with the specified name, creates a client secret, and assigns all required API permisions and Exchange admin roles to the app.

If the app registration succeeds, the script outputs the Application (client) ID, Directory (tenant) ID, and Client Secret into the console. If the app registration fails at any point, the script rolls back the changes in your Entra ID.

In the script:

• $appName – the display name for the app registration.
• $redirectUri – the URI of your Adaxes web interface. For example: https://server.example.com/Adaxes.
• $secretDisplayName – a friendly name for the client secret.
• $secretExpiryDaysFromNow – number of days until the client secret expires.
• $roleGroupName – the name of the Exchange role group that will contain all required roles.
• $maxAttempts – the maximum number of attempts to create the Exchange service principal. Sometimes the principal is not created on the first attempt because of propagation delays in Entra ID.

# Aplication registration parameters.
$appName = "Adaxes App"
$redirectUri = "https://server.example.com/Adaxes"
$secretDisplayName = "Adaxes Client Secret"
$secretExpiryDaysFromNow = 730 # 2 years
$roleGroupName = "Adaxes Application Role Group"
$maxAttempts = 5

# Required API permissions for the application.
$requiredResourceAccess = @(
    @{
        resourceAppId  = "00000003-0000-0000-c000-000000000000" # Microsoft Graph
        resourceAccess = @(
            @{ id = "b0afded3-3588-46d8-8b3d-9842eff778da"; type = "Role" } # AuditLog.Read.All
            @{ id = "9a5d68dd-52b0-4cc2-bd40-abcf44ac3a30"; type = "Role" } # Application.Read.All
            @{ id = "62a82d76-70ea-41e2-9197-370581804d09"; type = "Role" } # Group.ReadWrite.All
            @{ id = "9492366f-7969-46a4-8d15-ed1a20078fff"; type = "Role" } # Sites.ReadWrite.All
            @{ id = "741f803b-c850-494e-b5df-cde7c675a1ca"; type = "Role" } # User.ReadWrite.All
            @{ id = "50483e42-d915-4231-9639-7fdb7fd190e5"; type = "Role" } # UserAuthenticationMethod.ReadWrite.All
            @{ id = "cc117bb9-00cf-4eb8-b580-ea2a878fe8f7"; type = "Role" } # User-PasswordProfile.ReadWrite.All
            @{ id = "3011c876-62b7-4ada-afa2-506cbbecc68c"; type = "Role" } # User.EnableDisableAccount.All
            @{ id = "5facf0c1-8979-4e95-abcf-ff3d079771c0"; type = "Role" } # LicenseAssignment.ReadWrite.All
            @{ id = "9241abd9-d0e6-425a-bd4f-47ba86e767a4"; type = "Role" } # DeviceManagementConfiguration.ReadWrite.All
            @{ id = "9e3f62cf-ca93-4989-b6ce-bf83c28f9fe8"; type = "Role" } # RoleManagement.ReadWrite.Directory
        )
    },
    @{
        resourceAppId  = "00000002-0000-0ff1-ce00-000000000000" # Exchange Online
        resourceAccess = @(
            @{ id = "dc50a0fb-09a3-484d-be87-e023b12c6440"; type = "Role" } # Exchange.ManageAsApp
            @{ id = "7146a1f0-8703-45b3-9eae-527a64c00995"; type = "Role" } # SMTP.SendAs.App
        )
    }
)

# Required Exchange Online roles.
$roles = @(
    "Mail Recipients",
    "Mail Recipient Creation",
    "Distribution Groups",
    "Security Group Creation and Membership",
    "Move Mailboxes",
    "Retention Management",
    "Organization Client Access"
)

# Ensure the required modules are installed.
if (-not (Get-Module -ListAvailable Microsoft.Graph)) { throw "Microsoft.Graph module not found." }
if (-not (Get-Module -ListAvailable ExchangeOnlineManagement)) { throw "ExchangeOnlineManagement module not found." }

try {
    # Connect to Exchange Online and Microsoft Graph.
    Connect-MgGraph -Scopes "Application.ReadWrite.All", "AppRoleAssignment.ReadWrite.All"
    Connect-ExchangeOnline
}
catch { throw "Failed to connect to Entra ID or Exchange Online: $_" }

# Verify that the specified app and role group name is unique.
if (Get-MgApplication -Filter "displayName eq '$appName'") { throw "An app named '$appName' already exists." }
if (Get-RoleGroup -Identity $roleGroupName -ErrorAction SilentlyContinue) { throw "A role group named '$roleGroupName' already exists." }

try {
    # Create Entra application registration and service principal.
    $app = New-MgApplication `
        -DisplayName $appName `
        -RequiredResourceAccess $requiredResourceAccess `
        -Spa @{ RedirectUris = @($redirectUri) } `
        -ErrorAction Stop
    $secret = Add-MgApplicationPassword `
        -ApplicationId $app.Id `
        -PasswordCredential @{
        DisplayName = $secretDisplayName
        EndDateTime = (Get-Date).AddDays($secretExpiryDaysFromNow)
    } `
        -ErrorAction Stop
    $servicePrincipal = New-MgServicePrincipal -AppId $app.AppId

    # Grant admin consent for the API permissions.
    foreach ($resource in $requiredResourceAccess) {
        $resourceAppId = $resource.resourceAppId
        $targetApi = Get-MgServicePrincipal -Filter "appId eq '$resourceAppId'"

        foreach ($permission in $resource.resourceAccess) {
            $params = @{
                "PrincipalId" = $servicePrincipal.Id
                "ResourceId"  = $targetApi.Id
                "AppRoleId"   = $permission.Id
            }
            New-MgServicePrincipalAppRoleAssignment -ServicePrincipalId $servicePrincipal.Id -BodyParameter $params
        }
    }

    # Create a service principal in Exchange Online.
    $exchangeServicePrincipal = $null
    $attempt = 0
    while ($attempt -lt $maxAttempts -and -not $exchangeServicePrincipal) {
        $attempt++
        try {
            $exchangeServicePrincipal = New-ServicePrincipal `
                -AppId $app.AppId `
                -ObjectId $servicePrincipal.Id `
                -DisplayName $appName `
                -ErrorAction Stop
            break
        }
        catch {
            if ($attempt -ge $maxAttempts) {
                throw "Exchange service principal creation failed after $maxAttempts attempts."
            }
            $retryInterval = $attempt * $maxAttempts
            Write-Warning "Attempt $attempt to create Exchange service principal failed. Retrying in $retryInterval seconds."
            Start-Sleep -Seconds $retryInterval
        }
    }
    
    # Create a role group in Exchange Online and assign it to the service principal.
    $roleGroup = New-RoleGroup `
        -Name $roleGroupName `
        -Roles $roles `
        -Members $exchangeServicePrincipal `
        -ErrorAction Stop
}
catch {
    Write-Error "Failed to create the application registration: $_"
    if ($app) {
        # Remove incomplete application registration.
        Remove-MgApplication -ApplicationId $app.Id -Confirm:$false
    }
    if ($exchangeServicePrincipal) {
        # Remove Exchange service principal.
        Remove-ServicePrincipal -Identity $exchangeServicePrincipal -Confirm:$false
    }
    if ($roleGroup) {
        # Remove Exchange role group.
        Remove-RoleGroup -Identity $roleGroupName -Confirm:$false
    }
    return
}

# Output a summary of the created application.
Write-Host `n"App '$appName' created successfully."
Write-Host "Application ID: $($app.AppId)"
Write-Host "Tenant ID: $((Get-MgOrganization).Id)"
Write-Host "Client Secret: $($secret.SecretText)"

# Disconnect from Microsoft Graph and Exchange Online.
Disconnect-MgGraph | Out-Null
Disconnect-ExchangeOnline -Confirm:$false

The script deletes the app registration with the specified name from you Entra ID, deletes the related Entra and Exchange service principals, and deletes the role group created for the app in Exchange.

In the script:

• $appName – the display name of the app registration.
• $deleteRoleGroup – set to $true to delete the role created during app registration, or set to $false to leave it in Exchange Online.

$appName = "Adaxes App"
$deleteRoleGroup = $true

try {
    # Connect to Exchange Online and Microsoft Graph.
    Connect-MgGraph -Scopes "Application.ReadWrite.All", "AppRoleAssignment.ReadWrite.All"
    Connect-ExchangeOnline
}
catch { throw "Failed to connect to Entra ID or Exchange Online: $_" }
    
# Find the app and the Exchange service principal.
$app = Get-MgApplication -Filter "displayName eq '$appName'"
if (-not $app) { throw "App '$appName' not found." }
$servicePrincipal = Get-ServicePrincipal $app.AppId
if (-not $servicePrincipal) { throw "Exchange service principal for app '$appName' not found." }

# Remove any role groups assigned to the app.
if ($deleteRoleGroup) {
    $roleGroups = Get-RoleGroup | Where-Object { $_.Members -contains $servicePrincipal.Id }
    if ($roleGroups) {
        $roleGroups | ForEach-Object { Remove-RoleGroup $_ -Confirm:$false }
    }
    else {
        Write-Host "No role groups assigned to '$appName' found."
    }
}

# Remove the Exchange service principal and the app registration.
Remove-ServicePrincipal -Identity $servicePrincipal.Id -Confirm:$false
Remove-MgApplication -ApplicationId $app.Id -Confirm:$false

# Disconnect from Microsoft Graph and Exchange Online.
Disconnect-MgGraph | Out-Null
Disconnect-ExchangeOnline -Confirm:$false