TDC ERHVERV Azure App Integration User Guide
- July 26, 2024
- TDC
Table of Contents
TDC ERHVERV Azure App Integration
Introduction
This guide will walk you through the process of creating an app registration and installing the Integration App in Azure. It includes steps such as checking your Azure subscription, creating a resource group and app registration, and installing the Integration App. Additionally, it provides an optional security review of the app. The guide provides clear steps and instructions, including information on necessary IDs and keys. After installation, you can enable various operations within the app based on JSON content, such as self-testing, inspection, and control of Teams telephony. It is important to follow the instructions not to modify the Powershell code and to take note of important information like app keys and URLs. This guide will help you set up the Integration App correctly and use its features to enhance your business communication with TDC Business Selfservice.
-
Prepare the Target Tenant
It is assumed that you have followed this guide: https://tdc.dk /implementation-guide-teams. This ensures that your Azure Tenant is configured for telephony, connected to a Supertrunk, and that the Supertrunk is linked to a Broadworks trunk. -
Creating an App-registration for Graph access and integrating it with Selfservice
This is described in this guide: https://tdc.dk/kundeservice/telefoniloesning/tjenester/teams-telefoni/opsaet- ad-integration -
Creating an App-registration for the intergration App and Installing the Integration App
Log in-to the target Azure Tenant on https://portal.azure.com/ using an account that is Administrator. If you are not a Billing Administrator some of the steps below will not work for you.
Check your Azure Subscription
Before we start, let’s make sure your Azure Tenant has an active Subscription.
This is necessary because the Integration App consumes cloud storage and CPU
cycles whenever it is triggered. Azure must be able to bill these expenses,
and this requires a Subscription.
Search for Subscriptions and go to that section by clicking the Subscriptions link with the yellow key icon.
Your organization may have more than one Subscription listed here. Be sure you have decided on which one to use and double check that it is Active.
Make a note of the Subscription name, we will need it later. In this example we will be using a Subscription called Bluetest4 Azure Plan.
Create a Ressource group and find the Tenant ID
The Integration App will need to be installed into a new empty Azure
Resource group. Search for Resource groups and go to that section.
You may already have several resource groups already listed here, ignore those, and click the plus-icon to create a new empty resource group.
You should see a page that looks like this.
- Choose the Azure Subscription that we found in the section above. This will be billed for the storage and CPU cycles consumed by the Integration App once it is installed.
- You can enter any (locally unique) name for your new group, in this example we will call it TDC_Erhverv_Telephony_Integration.
- Choose a region that is geographically close to the TDC Erhverv servers, for example “(Europe) North Europe”.
Click Review + create. And then on the next page click Create. (Pro tip: if your accounting department wants telephony related cloud resources grouped together, you can optionally add some helpful Tags).
Remember the name of your new empty Resource group, we will need it later.
We will also need to note down the global ID of your tenant. To find it search for Microsoft Entra ID and go to that section.
You can now read off the Tenant ID. In this example it is 52d54f0b-90ea-450b- be8b-acd3d8c7a201. Note it down, we will need it in the next section.
At this point we should have noted down:
- Subscription name: Bluetest4 Azure Plan (we used it in this section but will need it again later)
- New empty resource group, located in northern Europe: TDC_Erhverv_Telephony_Integration
- Your Azure Tenant ID: 52d54f0b-90ea-450b-be8b-acd3d8c7a201
Creating an App registration
When we install the App, it will need to be configured with credentials, we
provide these by making a new App-registration and configuring it with the
required permissions.
Let’s get started. Search for App registration and click on the link to go
there.
From the section App registration choose the tab All applications. If you have already completed the guide Opsæt AD-integration you should already have a registration here called TDC Erhverv Selvbetjening. If you don’t, this is fine. You can come back and create this other registration later.
Now click the link at the top with the plus-sign called New registration.
- You can name the new registration anything, but in this example, we will call it TDC Erhverv Telephony Integration. Remember this name, we will need it later.
- Under Supported account typed choose Accounts in this organizational directory only (Single tenant).
- Don’t enter any value for the section Redirect URI.
Click the Register button at the bottom.
You should now see the Overview page for your new App-registration. From this page note down the Application (client) ID, in this example it is 3068f451 -4cfb-4c68-b213-2b39a269e693, and save it, we will need it later.
Next click the section Certificate & secrets in the menu bar on the left. You
should now see this page.
Click the plus-icon New client secret.
This is the secret that we will later give the Integration App so that it may use the identity of this App registration when performing telephony related operations in your Teams setup.
- You can add any Description you want, but in this example, we will call it TDC Erhverv Telephony Integration.
- You can choose any Expires date you want. We recommend choosing the max.: 24 months – this way you will not have to reconfigure your App for at least two years.
- When you are done click the button Add at the button.
You have now created a new secret. Do not share this with anyone, not even TDC Erhverv. You will need to note down the secret value, we will need this later. Be aware that once you leave this page the value can never be displayed again – so note it down now. (Pro tip: If you lose the value of your secret, just delete is and make a new one). In this example the value of our secret is xDn8Q~GpsHX9BnvlgJrhy~s9uuUxY8T1A~iMIa8I.
You should also make a note of the secret expire date. In this example it is 2025-09-10. It is good practice to set yourself a reminder to come back and update the secret (see our PDF-file for this on page) two weeks before the secret expires.
The new App registration by itself can’t do much. Now we will grant it the permissions it needs to update Teams telephony setting. Search for the section called Microsoft Entra ID roles and administration and go there.
Now search for the role called Teams Communications Administrator. Click the name of the role (not the check box) to proceed.
On this page you may already have this role assigned to someone. In this example we do not. In either case click the plus-icon at the top to add a new assignment.
On this page, don’t bother scrolling through the user list looking for your new App-registration. It will not appear there until we search for it.
Remember the name we gave the new registration above and type this into the search field. Now click the check box to mark the registration and click Add.
The App registration will now appear on the list of entities that have the role Teams Communications Administrator. Remember that this is a highly privileged administrator role. Do not give the App registration secret value to anyone, not even TDC Erhverv.
Installing the Intergration App
If you have followed the sections above, you should now have five pieces of information ready.
- Subcription name: Bluetest4 Azure Plan
- Tenant ID: 52d54f0b-90ea-450b-be8b-acd3d8c7a201
- Name of new empty Resource group: TDC_Erhverv_Telephony_Integration
- App-registration Application (client) ID: 3068f451-4cfb-4c68-b213-2b39a269e693
- App-registration Application secret value: xDn8Q~GpsHX9BnvlgJrhy~s9uuUxY8T1A~iMIa8I Now search for Marketplace and click the link to go to that section.
Search for TDC, and find the App called TDC Erhverv Telephony Integration (don’t pick ”TDC Erhverv Teams Telephony” by mistake). The search result should look like this.
Click on TDC Erhverv Telephony Integration and select the latest version in the drop down. Now click Create.
Fill out the fields with the information we prepared above. Be sure to select North Europe as the region since this is close to the TDC Erhverv servers.
Click Review + create.
Then click Create.
The installation will take a few minutes.
When you see this, you know the installation has completed.
Preparing the App’s external API credentials
To have a closer look at the App we just installed, navigate to the resource
group that contains it. Do this by searching for Resource groups and clicking
the icon.
Now click on the name (not the check box) of the resource group we selected while installing the App.
You will find the App-offer we installed from Marketplace has created seven resources in the resource group. The resource marked Function App is the App itself, the rest are cloud infrastructure that the App need to function. Click the Function App resource with the lightning bolt icon to take a closer look at the internal logic of the App (click the name, not the check box).
From the Overview section copy the URL and save it, we will need this later. In this example the URL is https://nuudaytob-5sutozr67fiik.azurewebsites.net but every time you install a copy of the App a new globally unique public URL will be created. Next click the App keys menu point on the left-hand side.
You will find that the installation process has created two keys ”_master” and ”default”. You should keep these private and create a dedicated App key for integrating with the TDC Erhverv Selfservice portal. Click the plus-icon named New host key at the top to create a new key.
You can name the key anything you like; in this example we will call it ”TDC_Selfservice”. Leave the value blank to have Azure auto-generate a strong key for you, then click the link in the bottom right-hand corner called Generate a random key value and save.
You now have a new app key. Make a note of it, we will need it later. You can always come back here and copy the value again if you lose it. This key will never expire, but if at any point you would like to cut off TDC Erhverv’s access to your App, then come back here and delete the key. In our example the key is 3Br2w2pK1I6qflrlLnMvZl-sMQk2Fj58amQx1Ng-nogoAzFuTsZg4g==
You should now have:
- App URL: https://nuudaytob-5sutozr67fiik.azurewebsites.net
- App key: 3Br2w2pK1I6qflrlLnMvZl-sMQk2Fj58amQx1Ng-nogoAzFuTsZg4g==
You can now proceed to integrate the App with the TDC Erhverv Self service portal, but you may want to go through the next optional step first.
(Optional ) App Security Review
Before handing over the App key to TDC Erhverv you may be required to have
your local security team review function inside the App. Fortunately all logic
inside the App is fully visible and is managed and controlled by you. If you
ever re-install a newer updated version of the App you may want to perform
this review again since the content may have changed. First navigate back to
the Function App Overview section. At the bottom in the middle are listed all
the internal functions that make up this App. Currently there is only one. We
call it ”psweb” (aka. Powershell Webservice). Click on it to inspect it.
From here navigate to the section Code + test.
This is the internal Powershell ”payload” that is run whenever the API of the surrounding App is called by TDC Erhverv. This code cannot be changed by the external caller. Make a copy and pass it on to your security review team if your company governance practices require this.
You will find that the code can be triggered to perform four different operations depending on the JSON body of the incoming request.
| Operation | JSON input | Description |
|---|---|---|
| App self-test | { |
“function”:”Test”
}
| Is the App installed and configured correctly.
App inspection| {
“function”:”Dump”
}
| Check the presence of all App files and show their current MD5 sum. Only the
sum is returned, never the file content.
Voice-enable a target Teams-user| {
“function”:”Enable”, “VKID”:”
}
| Instruct the App enable Teams-calling and assign the given phone number on
the target user.
Voice-disable a target Teams-user| {
“function”:”Disable”, “Identity”:”
}
| Remove Teams-calling on the target user.
These operations will be called by the Order Management system of the TDC Erhverv Selfservice system. We do not recommend you run the voice- enable/disable operations by yourself since they require synchronization with the TDC Erhverv telephony system, but at any point you can run the self-test and inspect operations to diagnose App health.
Please do not make any modifications to the Powershell code. Even once character out of place in this file will change its MD5 sum. If TDC Erhverv ever finds an app where the MD5 sum does not match what was delivered with that version of the Marketplace Offer, then support will not be available, and any unexpected side-effects of your local modifications will not be covered.
Example 1:
curl https://nuudaytob
5sutozr67fiik.azurewebsites.net/api/psweb?code=3Br2w2pK1I6qflrlLnMvZl
sMQk2Fj58amQx1Ng nogoAzFuTsZg4g==
d ‘{“function”:”Test”}’
H “Content Type: application/json” X GET
Expected response:
“appVersion”: ”
“command”: ”
“success”:
“message”:
“resultCode”: ”
Example 2:
curl https://nuudaytob
5sutozr67fiik.azurewebsites.net/api/psweb?code=3Br2w2pK1I6qflrlLnMvZl
sMQk2Fj58amQx1Ng nogoAzFuTsZg4g==
d ‘{“function”:”Dump”}’
H “Content Type: application/json” X GET
Expected respons:
Documents / Resources
| TDC
ERHVERV Azure App
Integration
[pdf] User Guide
ERHVERV Azure App Integration, ERHVERV Azure App, Azure App, App Integration,
Azure, App
---|---