Register Adaxes as an app in Entra ID

Registering Adaxes as an app in Microsoft Entra ID establishes a trust between Adaxes and the Microsoft identity platform. This allows Adaxes to perform operations in Entra ID, Microsoft 365, and Exchange Online via the registered app.

The app registration can serve two purposes:

  • Enable Adaxes to manage Entra ID, Microsoft 365, and Exchange Online
  • Enable Adaxes to securely send email notifications via Exchange Online

This article explains how to register and configure the app to manage your Entra organization. For details on how to configure the app to send emails, see Configure mail settings.

Create application

  1. Sign in to the Microsoft Entra admin center.

  2. Navigate to and open the App registrations service.

    To quickly locate the service, type App registrations in the Search field.

  3. Click New registration.

  4. Enter the application name (e.g. Adaxes), and click Register.

  5. Copy the Application (client) ID and paste it into the Application (client) ID field in Adaxes administration console.

  6. Copy the Directory (tenant) ID and paste it into the Directory (tenant) ID field in Adaxes administration console.

  7. Back on the app page in the Microsoft Entra admin center, click Add a certificate or secret.

  8. Click New client secret and then click Add.

  9. Copy the client secret Value and paste it into the Client secret field in Adaxes administration console.

Do not click Next in the Administration console yet, as you need to grant the newly registered app the required permissions first.

Add API permissions

The app requires certain API permissions to enable Adaxes to manage your Microsoft Entra domain or Microsoft 365 tenant. Tenant management requires fewer permissions than domain management.

  • Permission

  • Reason

  • Exchange.ManageAsApp

  • Connect to Exchange Online.

  • User.ReadWrite.All

  • View, create, update, and delete user accounts.

  • User-PasswordProfile.ReadWrite.All

  • Reset users' passwords.

  • UserAuthenticationMethod.ReadWrite.All

  • Reset users' multifactor authentication methods.

  • User.EnableDisableAccount.All

  • Enable and disable accounts of role-assignable group members.

  • LicenseAssignment.ReadWrite.All

  • Assign and revoke Microsoft 365 licenses.

  • AuditLog.Read.All

  • Read users' last sign in information. Domain management only.

  • Sites.ReadWrite.All

  • Modify properties stored in external sources e.g. employee hire date stored in SharePoint. Domain management only.

  • Group.ReadWrite.All

  • View, create, update, delete groups and add/remove group members. Domain management only.

  • RoleManagement.ReadWrite.Directory

  • Create role-assignable groups. Domain management only.

Add these API permissions via the app manifest:

  1. On the app page in the Microsoft Entra admin center, click Manifest to open up an editor that allows you to directly edit the attributes of the app registration.

  2. Locate the requiredResourceAccess key in the manifest.

  3. Set the key to one of the values below, depending on the function that your Entra app will perform.

     Domain / tenant management and sending emails

    Select one of these values if you will use the app to manage your domain or tenant and send emails.

    Entra domain and Microsoft 365 tenant
    "requiredResourceAccess": [
    {
        "resourceAppId": "00000002-0000-0ff1-ce00-000000000000",
        "resourceAccess": [
            {
                "id": "dc50a0fb-09a3-484d-be87-e023b12c6440",
                "type": "Role"
            },
            {
                "id": "7146a1f0-8703-45b3-9eae-527a64c00995",
                "type": "Role"
            }
        ]
    },
    {
        "resourceAppId": "00000003-0000-0000-c000-000000000000",
        "resourceAccess": [
            {
                "id": "b0afded3-3588-46d8-8b3d-9842eff778da",
                "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": "741f803b-c850-494e-b5df-cde7c675a1ca",
                "type": "Role"
            },
            {
                "id": "50483e42-d915-4231-9639-7fdb7fd190e5",
                "type": "Role"
            },
            {
                "id": "3011c876-62b7-4ada-afa2-506cbbecc68c",
                "type": "Role"
		    }
        ]
    }
]
    Microsoft 365 tenant
    "requiredResourceAccess": [
    {
        "resourceAppId": "00000002-0000-0ff1-ce00-000000000000",
        "resourceAccess": [
            {
                "id": "dc50a0fb-09a3-484d-be87-e023b12c6440",
                "type": "Role"
            },
            {
                "id": "7146a1f0-8703-45b3-9eae-527a64c00995",
                "type": "Role"
            }
        ]
    },
    {
        "resourceAppId": "00000003-0000-0000-c000-000000000000",
        "resourceAccess": [
            {
                "id": "5facf0c1-8979-4e95-abcf-ff3d079771c0",
                "type": "Role"
            },
            {
                "id": "cc117bb9-00cf-4eb8-b580-ea2a878fe8f7",
                "type": "Role"
            },
            {
                "id": "741f803b-c850-494e-b5df-cde7c675a1ca",
                "type": "Role"
            },
            {
                "id": "50483e42-d915-4231-9639-7fdb7fd190e5",
                "type": "Role"
            },
            {
                "id": "3011c876-62b7-4ada-afa2-506cbbecc68c",
                "type": "Role"
		    }

        ]
    }
]
     Only domain / tenant management

    Select one of these values if you will use the app to only to manage your domain or tenant.

    Entra domain and Microsoft 365 tenant
    "requiredResourceAccess": [
    {
        "resourceAppId": "00000002-0000-0ff1-ce00-000000000000",
        "resourceAccess": [
            {
                "id": "dc50a0fb-09a3-484d-be87-e023b12c6440",
                "type": "Role"
            }
        ]
    },
    {
        "resourceAppId": "00000003-0000-0000-c000-000000000000",
        "resourceAccess": [
            {
                "id": "b0afded3-3588-46d8-8b3d-9842eff778da",
                "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": "741f803b-c850-494e-b5df-cde7c675a1ca",
                "type": "Role"
            },
            {
                "id": "50483e42-d915-4231-9639-7fdb7fd190e5",
                "type": "Role"
            },
            {
                "id": "3011c876-62b7-4ada-afa2-506cbbecc68c",
                "type": "Role"
		    }
        ]
    }
]
    Microsoft 365 tenant
    "requiredResourceAccess": [
    {
        "resourceAppId": "00000002-0000-0ff1-ce00-000000000000",
        "resourceAccess": [
            {
                "id": "dc50a0fb-09a3-484d-be87-e023b12c6440",
                "type": "Role"
            }
        ]
    },
    {
        "resourceAppId": "00000003-0000-0000-c000-000000000000",
        "resourceAccess": [
            {
                "id": "cc117bb9-00cf-4eb8-b580-ea2a878fe8f7",
                "type": "Role"
            },
            {
                "id": "741f803b-c850-494e-b5df-cde7c675a1ca",
                "type": "Role"
            },
            {
                "id": "50483e42-d915-4231-9639-7fdb7fd190e5",
                "type": "Role"
            },
            {
                "id": "5facf0c1-8979-4e95-abcf-ff3d079771c0",
                "type": "Role"
            },
            {
                "id": "3011c876-62b7-4ada-afa2-506cbbecc68c",
                "type": "Role"
		    }
        ]
    }
]

  4. Click Save.

  5. Click API permissions.

  6. Verify that the list contains the required permissions.

  7. Click Grant admin consent for <tenant name> and then click Yes to confirm. Admin consent is required to make the added permissions effective.

Assign Exchange roles to the app

The app requires the following admin roles to manage Exchange Online.

  • Role

  • Reason

  • Mail Recipients

  • Manage existing mailboxes, mail users, and mail contacts. Verify that all the required roles are assigned to the Adaxes application in Exchange Online.

  • Mail Recipient Creation

  • Create mailboxes, mail users, mail contacts, and distribution groups.

  • Distribution Groups

  • Create and manage distribution groups and their members.

  • Security Group Creation and Membership

  • Create and manage mail-enabled security groups and their members.

  • Move Mailboxes

  • Move mailboxes between servers in an organization.

  • Retention Management

  • Manage retention policies.

  • Organization Client Access

  • Define which Exchange ActiveSync mobile devices are allowed.

There is a slight caveat – you cannot assign Exchange admin roles directly to an Entra app. You need to first create a corresponding Exchange service principal, and then assign the roles to this principal. This can only be done via PowerShell.

  1. Launch Windows PowerShell on the computer where the ExchangeOnlineManagement PowerShell module is installed.

  2. Execute the following script. It will create an Exchange service principal for your app if there isn't already one, combine the required roles into a role group, and add the app to the role group.

    In the script:

    • $applicationId – the identifier of the app registration in Entra ID.

    • $entraServicePrincipalId – the identifier of the Entra service principal of the app.

       How to obtain the application and service principal identifiers

      1. Open the Microsoft Entra admin center.

      2. Navigate to and open the Enterprise applications service.

      3. Locate your application and click it.

      4. The app registration and service principal identifiers will be displayed in the Properties section, in the Application ID and Object ID fields respectively.

      Important

      Do not confuse these identifiers with the ones on the app page of the App registrations service. Those identifiers are different and will not work.

    • $displayName – a user-friendly display name for the new service principal.

    • $roleGroupName – the name of the new role group that will contain all the permissions required by Adaxes. For example, Adaxes app permissions.

    $applicationId = "<appID>"
$entraServicePrincipalId = "<objectID>"
$displayName = "<displayName>"
$roleGroupName = "<roleGroupName>"

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

Connect-ExchangeOnline
try 
{
    $servicePrincipal = Get-ServicePrincipal -Identity $applicationId -ErrorAction Stop
}
catch 
{
    $servicePrincipal = New-ServicePrincipal `
        -AppId $applicationId -ObjectId $entraServicePrincipalId -DisplayName $displayName
}
New-RoleGroup -Name $roleGroupName -Roles $roles -Members $servicePrincipal.Identity

  3. Finally, go back to the Adaxes administration console, click Next, and follow the instructions in the wizard.

© Softerra 2022. All rights reserved.
Contact us