Microsoft Entra ID for Gatekeeper

Entra ID integration is available for the following user types:

Web Agent Console (WAC agents)
Web Admin Portal (web users)
Interactive Voice Response (API developers)
Voice ID (users)

Note:

To configure the Microsoft Entra ID for Gatekeeper, you must have the Global Admin access for the tenant in the Azure portal.

Do the following steps to configure the Microsoft Entra ID for Gatekeeper API:

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.
Create a service principal (local representation of the Gatekeeper 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 Gatekeeper API:
```
POST https://graph.microsoft.com/v1.0/servicePrincipals
{
    "appId": "<Gatekeeper API App ID>"
}
```
    See Entra ID App IDs for <Gatekeeper 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 <Gatekeeper API App ID>
```
    See Entra ID App IDs for <Gatekeeper API App ID>.
Register your application to create a client service principal.
- 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.
    
    Note:
    While registering the app, ensure that you select the single tenant option, and don’t add any redirect URIs.
    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>
```
  where, <your client service principal> is the name of the app.
Optionally, you can configure API permissions to client service principal for voice ID users only.
- Using the Azure portal:
  1. Go to App Registration and refresh the page.
  2. Select the All applications tab and click the app you created.
  3. From Manage, select API permissions. Click + to add a permission.
  4. From Request API permission, select APIs my organization uses. In the filter text box, enter <Gatekeeper API App ID>.
  5. Click the Gatekeeper API search result and select Application permissions.
  6. Select vsignin.admin and vsignin.auth roles, click Add permissions.
- Alternatively, you can use Azure CLI to configure API permissions.
  1. Run the following command to extract a resource access snippet from Gatekeeper API service principal:
```
az ad sp show --id <Gatekeeper API App ID> --query "[{resourceAppId: appId, resourceAccess: appRoles[].{id: id, type: 'Role'}}]" > resource.json
```
    The command creates a JSON file with the following format:
```
[
  {
    "resourceAppId": "<Gatekeeper API App ID>",
    "resourceAccess": [
      {
        "id": "<vsignin.admin Role ID>",
        "type": "Role"
      },
      {
        "id": "<vsignin.auth Role ID>",
        "type": "Role"
      }
    ]
  }
]
```
  2. Run the following command to configure API permissions to client service principal:
```
az ad app update --id <Your ClientID> --required-resource-accesses resource.json
```
Using the Azure portal, grant Admin Consent for Gatekeeper API.
1. Go to Entra ID and select App Registration. Refresh the page.
2. Select the All applications tab and click the app you created.
3. Click API permissions on the left-hand side menu.
4. Click the Grant admin consent for <your tenant name>. Click Yes to confirm.
After the app registration is done, create the client secret for the app.
1. Go to App Registration and refresh the page.
2. Select the All applications tab and click the app you created.
3. From Manage, select Certificates & Secrets to create a new client secret. For more information, see Create a new client secret .
From Manage, go to Enterprise applications and search for <your client name> or App ID (or client ID). To know more, see view enterprise applications .
Contact the Nuance team with the tenant ID, client ID, and object ID of the client service principal linked to the created client app registration for authorization to call Gatekeeper API.

Once you get authorization access from the Nuance team, you can generate the token using your client ID and secret to the call Gatekeeper API. Following is the sample code to generate the token:

curl -s -u "<YourClientID>:<YourClientSecret>" "https://login.microsoftonline.com/<your tenant id>/oauth2/v2.0/token" -d "grant_type=client_credentials" -d "scope=<GK API App ID>/.default" --ssl-no-revoke

Contact the Nuance team with the client ID so that it can be added to the Authorization Management’s members and issuers page in the Gatekeeper web portal. For more information, see Manage members and Add user-friendly display names for issuers.