Create Application Registration in Microsoft Cloud Tenant Portal#

Overview#

The application object describes VOSS Automate to Microsoft Entra, allowing the Microsoft Entra service to issue authentication tokens to the VOSS Automate service.

This procedure registers VOSS Automate as an application object in Microsoft Entra (the Microsoft Cloud), adds a client secret and/or a certificate (for authentication with the Microsoft identity platform), configures API permissions, creates, exports, and uploads a self-signed certificate, and adds VOSS Automate to the Exchange administrator role.

Note

Microsoft changed the name of Azure Active Directory to Microsoft Entra ID in August 2023. In this documentation, references to the Microsoft Cloud portal also refer to Microsoft Entra ID.

The diagram describes the tasks involved in the app registration:

@startuml
'Create application registration in MS Cloud
!include style.iuml
start
:[[../src/user/register-voss-app-in-azure.html#step-1-register-application-with-microsoft-entra Register VOSS Automate as an application with MS Entra]];
:[[../src/user/register-voss-app-in-azure.html#step-2-configure-microsoft-graph-authentication Configure MS Graph authentication method]];
note right
 Two authentication methods (use either, or both):
   * [[../src/user/register-voss-app-in-azure.html#add-certificate-authentication Certificate authentication]])
   * [[../src/user/register-voss-app-in-azure.html#add-client-secret-authentication Client secret authentication]])
end note
:[[../src/user/register-voss-app-in-azure.html#step-3-add-microsoft-graph-api-permissions Add MS Graph API and application permissions]];
stop
@enduml

Important

When performing this task, take note of the following values, which you’ll need to set up the tenant connection in VOSS Automate:

  • Directory (tenant) ID (Tenant ID field in VOSS Automate)

  • Application (client) ID (Client ID field in VOSS Automate)

  • Client secret (Secret field in VOSS Automate)

You can retrieve your Tenant and Client IDs from Microsoft Entra at any time. But you’ll need to save your client secret in a secure location because it will be exposed only once. From a security perspective, treat these values as if they were administrative login credentials.

Step 1: Register VOSS Automate as an application with Microsoft Entra#

This step registers your application (VOSS Automate in this case) as an application in Microsoft Entra. This will allow Microsoft Graph to access Microsoft Entra.

  1. Use your Global Administrator credentials to sign into the Microsoft Cloud (Microsoft Entra) portal .

  2. Choose the tenant in which you want to register the VOSS Automate application.

    Note

    If you have access to multiple tenants, use the Directory + Subscription filter in the toolbar to choose the relevant tenant.

  3. Select Microsoft Entra service.

    Note

    Locate the service via Favorites > Microsoft Entra, or locate it in All services.

  4. Expand Microsoft Entra, then go to Applications > App registrations, and select New registration.

  5. Enter a name for your application, for example “VOSS Automate”.

    Note

    Your application users may see this name. You can change it later.

  6. Select Accounts in this organization only.

    You can ignore the Redirect URI section.

  7. Click Register.

Next steps

Step 2: Configure Microsoft Graph Authentication#

There are two authentication methods available for Microsoft Graph. You can add either of these authentication methods, or use both:

Note

Microsoft’s recommendation is to use certificate authentication for Microsoft Graph. A client secret takes precedence, if used; else, the certificate authentication is used (if available).

Add Client Secret Authentication#

  1. In the Microsoft Cloud (Microsoft Entra) portal , at App Registrations, choose the VOSS Automate application created in step 1, then go to Manage > Certificates & secrets and on the Client secrets tab, select New client secret.

  2. On the Add a client secret form, add a description, and choose an expiry option.

  3. Click Add.

    ../../_images/MSFT_4d57ce16a05261c5.png

    Important

    Make a note of the client secret and keep it in a safe location. You won’t be able to retrieve it if you lose it, and you need this value to set up VOSS Automate.

    If you lose the client secret you’ll have to delete it and repeat the steps for creating a new one.

    ../../_images/MSFT_bd385bd6a357b048.png

Next steps

Add a second authentication method (optional), or go to Step 3: Add Microsoft Graph API Permissions

Add Certificate Authentication#

This procedure adds and exports a self-signed certificate public key in VOSS Automate, and uploads the certificate to Microsoft Entra.

  1. Log in to the VOSS Automate Admin Portal, as a Customer administrator or higher.

  2. Go to (default menus) Administration Tools > Certificate Management.

  3. Click Add; then, fill out certificate details.

    1. On the Base tab:

      • Fill out a name and a description for the certificate.

      • Clear (unset) the Generate Certificate Signing Request checkbox to ensure no certificate signing request is generated. Disabling this option will ensure that the certificate will be self-signed.

      • In Valid To specify a value, in seconds, to define the validity period of the certificate from the time from generation. The default value is 315360000 seconds (10 years).

      • In Serial Number, choose a value or leave the default.

      • In Key Length, input a value of 2048 or greater for Microsoft Entra to accept the certificate for authentication.

    2. On the Certificate Information tab, fill out details for the certificate, including the name of the host being authenticated by the certificate, country code, state, city, organization, and organization unit.

      Note

      All fields are mandatory.

  4. Save the certificate.

  5. Click Action > Export Public Key to export a file containing the public key.

  6. Log in to the Microsoft Cloud (Microsoft Entra) portal , then go to Certificates & secrets.

  7. On the Certificates tab, click Upload certificate, then browse to the certificate you exported from the VOSS Automate Admin Portal.

  8. Copy the certificate thumbprint. You will need the certificate thumbprint (along with the tenant ID and client ID from Microsoft Entra) to configure the Microsoft tenant connection parameters.

Next steps

Step 3: Add Microsoft Graph API Permissions#

  1. In the Microsoft Cloud (Microsoft Entra) portal , go to Manage > API permissions > Add a permission.

    ../../_images/MSFT_f24dc7cfff59dc11.png
  2. Select Microsoft Graph.

    ../../_images/MSFT_e6d39996937914ef.png
  3. Select Application permissions, then choose the relevant permissions:

    Why required?

    Permission and description

    For Automate management of Microsoft Entra objects (functionality required by a user).

    Read is the basic requirement. ReadWrite can be used for managing user licenses, and user properties.

    • User.Read.All

      List MS Entra users, retrieve user properties (such as Usage Location), and license details. Use if you intend allowing the system to only read these objects.

    • Organization.Read.All

      List Microsoft subscribed SKUs (used and available licenses), and retrieve details (such as service plans).

    For adding, viewing, and managing MS Teams (teams and team members) in VOSS Automate

    In this case, Read is the minimum required permission. However, for managing team membership and assigning users to groups, ReadWrite is also required.

    • Team.Create

      Create teams

    • TeamMember.ReadWrite.All

      Create and edit team members. Use this permission if you plan to manage members of the Team via the system.

    • Group.Read.All

      Read all groups. Use this permission if you don’t intend to do any group management or user group assignments in the system.

    • GroupMember.ReadWrite.All

      Add, update, or delete groups and manage memberships. Use this permission if you intend to use the group management and user group assignment capabilities of the system.

    For managing Microsoft Teams channels in VOSS Automate.

    • Channel.ReadBasic.All

      Read channel names and descriptions.

    • Channel.Create

      Create channels in any team.

    • Channel.Delete.All

      Delete channels in any team.

    Domain permissions

    • Domain.Read.All

      Read all domain properties.

    Licensing permissions

    • LicenseAssignment.ReadWrite.All

      Assign and manage licenses.


  4. Click Add permissions.

    ../../_images/MSFT_dc4125b9da140c75.png
  5. To grant admin consent for the selected permissions, go to Configured permissions > Grant admin consent for <your tenant>, and click Yes to confirm.

    The status of selected permissions changes from Not granted to Granted.

    ../../_images/MSFT_50379baa9a20837f.png