Microsoft Entra ID for Connectors

Do the following steps to configure the Microsoft Entra ID for Connectors:

  1. Share the tenant ID with the Nuance team. If you have existing tenant, see Find your tenant ID  and Use an existing Microsoft Entra tenant  . To request the registration of your tenant ID into ASTRA, open a ticket. Without registration, the integration with Entra ID can’t work.

  2. Create a service principal (local representation of the Media Manager API App ID). You need to do this only once per tenant.

    • Using Graph Explorer:

      1. Go to Graph Explorer  and sign in as an admin on your tenant. You may need to consent to following permissions if you have any permission issues:

        • Application.ReadWrite.All
        • AppRoleAssignment.ReadWrite.All
        • ServicePrincipalEndpoint.ReadWrite.All

        See Microsoft Graph consent to permissions  for more information.

      2. Run the following query to grant your tenant access to the Media Manager API:

        POST https://graph.microsoft.com/v1.0/servicePrincipals
{
    "appId": "<Media Manager API App ID>"
}

        See Entra ID App IDs for <Media Manager API App ID>.

    • Alternatively, you can use Azure CLI to create a service principal:

      1. Login to Azure CLI as an admin.

        az login --tenant <tenant ID>

      2. Run the following command to create a service principal:

        az ad sp create --id <Media Manager API App ID>

        See Entra ID App IDs for <Media Manager API App ID>.

  3. Register your application to create a client service principal for each connector.

    • Using the Azure portal:

      1. Go to Manage Microsoft Entra ID.
      2. Under Manage, select App Registrations.
      3. Click New Registration to create a new app. Add a name of the app. For more information, see Register an application  .

    • Alternatively, you can use Azure CLI to create a client service principal:

        az ad sp create-for-rbac --name <your client service principal>

  4. Do the following steps to assign roles for every client service principal created for each of the following connectors: CTI, Media, and RCC.

    • Using the Azure portal:
      1. Go to Manage Microsoft Entra ID.
      2. Under Manage, select App Registrations.
      3. Click the app you created.
      4. Go to API Permissions and click Add a permission.
      5. Select APIs my organization uses.
      6. Search for the MediaManagerAPI app and select it.
      7. Add the desired permissions.
        • For CTI connector, add the following permissions:
          • connector.session
          • event.create
        • For Media connector, add the following permissions:
          • connector.session
          • connector.media
        • For RCC connector, add the following permissions:
          • connector.session
          • connector.rcc
      8. Once all the desired permission are added, click Grant admin consent for <your tenant> or ask admin to grant permissions.
    • Alternatively, you can use Graph APIs to assign roles to the client service principal.

      1. Go to Graph Explorer  and sign in as an admin on your tenant. Make sure you have consented to the permissions mentioned in step 2.

      2. Run the following query to get all the available roles that can be assigned to the client service principal:

        GET https://graph.microsoft.com/v1.0/servicePrincipals/<SP Object ID>/appRoles

where <SP Object ID> is the service principal object ID that you created in step 2.

        Following is the example output, such as for event.create:

        {
"allowedMemberTypes": [
    "Application"
],
"description": "Publish call and agent events ",
"displayName": "Event Create",
"id": "12345678-1234-1234-1234-123456789123",   # App Role ID. This is an example only.
"isEnabled": true,
"origin": "Application",
"value": "event.create"
}

        In this example, id is the <App Role ID> that you need to assign to the client service principal in the next step.

      3. Now you can assign roles using the following query:

        POST https://graph.microsoft.com/v1.0/servicePrincipals/<object ID of the app's service principal>/appRoleAssignments
{
    "principalId": "<Client's Service Principal Object ID>",
    "resourceId": "<App's Service Principal Object ID>",
    "appRoleId": "<App Role ID>"
}

 Where:
    <App's Service Principal Object ID> is the service principal object ID that you created in step 2.
    <Client's Service Principal Object ID> is the client service principal object ID that you created in step 3.

        For more information on the above query, see Assign user and groups to an application using Microsoft Graph API  .

  5. After the app registration is done, create the client secret or add the certificate for the app.

    • To create the client secret:
      1. Go to Microsoft Entra ID.
      2. Under Manage, select App Registrations.
      3. Click the app you created.
      4. Go to Certificates & Secrets.
      5. In the Client secret tab, click New client secret. For more information, see Create a new client secret 
      6. Enter the description and expiration date for the secret.
      7. Click Add to create the secret.
    • To add the certificate:

      1. Run the following bash script to generate the certificate for Connector (CTI, Media Connector, and RCC) and follow any prompts displayed:

        #!/bin/sh -x
#
set -eu

listOfOnPremConnectors="cti media rcc"

for connector in ${listOfOnPremConnectors}; do
    mkdir -p ./certs/${connector}
    pushd ./certs/${connector}

    read -s -p "Enter your password: " password

    openssl genrsa -des3 -passout pass:${password} -out ${connector}.pass.key 2048
    openssl rsa -passin pass:${password} -in ${connector}.pass.key -out ${connector}.key
    openssl req -new -key ${connector}.key -out ${connector}.csr
    openssl x509 -req -sha256 -days 365 -in ${connector}.csr -signkey ${connector}.key -out ${connector}.crt
    # private key must not be encrypted and can be PKCS1 or PKCS8 format
    openssl pkcs8 -topk8 -inform PEM -outform PEM -in ${connector}.key -out ${connector}_private_key.pkcs8 -nocrypt
    #optional. When not set CC will attempt to extract it from the above private key
    openssl rsa -passin pass:${password} -pubout -in ${connector}.pass.key -out ${connector}_publicKey.pem 

    popd
done

        The bash script generates various files in three different folders, one for each connector.

      2. Go to Manage Microsoft Entra ID.

      3. Under Manage, select App Registrations.

      4. Click the app you created.

      5. Go to Certificates & Secrets and select Certificates.

      6. Select Upload certificate to upload the certificate. For more information, see Upload a certificate 

      7. Click Add to upload the certificate.

  6. Go to the Azure portal’s Enterprise applications section, copy the application (service principal) object ID, and share it with the Nuance team for Media Manager API authorization.