[SAP & MS Teams] 7 – Get your Microsoft Azure settings ready

Welcome back to the blog post series about how to create your own Microsoft Teams extension for SAP solutions. In today’s seventh blog post, you will learn which further components need to be set up in the Microsoft Azure environment, to make your extension application work properly. Also, highly relevant settings for Principal Propagation are set in this chapter!

As explained in the first part (click here), this sample Microsoft Teams extension for SAP SuccessFactors will allow you to create leave requests right from within Microsoft Teams. It also provides features for managers to approve or reject leave requests. Again, this blog series has a special focus on those customers already using the SAP Business Technology platform in their landscape.

1. Preface and scenario introduction (click here)
2. Target application features (click here)
3. Requirements and application architecture (click here)
4. SAP BTP subaccount configuration and test users (click here)
5. SAP SuccessFactors instance setup (click here)
6. Set up your SAP Cloud Integration instance (click here)
7. Get your Microsoft Azure settings ready (this blog post)
   • Configure a new application registration for your extension application
   • Integrate your application with the SAP BTP enterprise application
   • Configure a Bot Service instance for your extension application
   • Create a Storage Account to store bot related data
8. Deploy your Microsoft Teams extension (click here)
9. Improvement ideas and further topics (click here)

A quick reminder for your convenience – Feel free to check out the GitHub repository provided in the SAP-samples organization. Please be aware, that the repository is still being updated, so make sure you’re pulling on a regular basis.

https://github.com/SAP-samples/btp-extend-workflow-cai-msteams/tree/full-scope

Another day another topic! Let’s find out about the important role of Microsoft Azure in this show! As you might have expected, it’s a quite central one, when it comes to security and Microsoft Teams integration! In the previous blog posts you’ve already configured some of the required settings (like the trust between SAP BTP and Azure Active Directory) but there is still some work left. So, without wasting any time, let’s kick it off!

As this blog post series has been highly inspired by the work of Martin Räpple, who is a Microsoft expert for security topics, please also check out his excellent blog post series, describing a lot of the following steps in further detail (click here).

Get your Microsoft Azure settings ready

A lot of developments in the Microsoft Azure environment start with setting up an app(lication) registration. So does this! An app registration allows you to authenticate against your Azure Active Directory and offers dedicated settings for authentication, permission handling and a lot more. In this case, you will create an application registration for your Microsoft Teams extension as it will interact with Microsoft Graph and SAP BTP using Azure Active Directory authentication features.

Register an application for your Microsoft Teams extension

To get the current scenario up and running, please make sure you’re following the instructions in this blog post and the Microsoft documentation in parallel. This will give you a better understanding of what is happening behind the scenes! Detailed information on how to create an application registration for a Microsoft Teams extension can be found on the following site (click here).

1) In your Azure Active Directory, create a new app registration for the Microsoft Teams extension application.

Hint – You will already see an existing application registration, which was created when you configured the trust between your SAP BTP subaccount and Azure Active Directory. This existing app registration will be used at a later point in time.

Create a new application registration

Give your application registration a meaningful name, like “Microsoft Teams Leave Request”.

Decide whether the app registration needs to be accessible from other organizational directories. In our landscape, the we enabled Multitenant usage, as our Azure Bot Service and Storage Account instances were created in a different directory. For the sake of simplicity and this demo’s purpose you should be fine selecting Multitenant.

For the Redirect URL, select type Web and insert a random https://-URL (e.g. https://localhost). This value will be changed at a later step of the current blog post. Click on Register to finish the registration process.

App registration sample

2) Once the registration is available, note down the Application Client Id from the Overview page.

Hint – It will later be used as <msappid-placeholder> and as MICROSOFT_APP_ID/ REACT_APP_MICROSOFT_APP_ID in the environment variables.

As you’ve got pen and paper ready, also note down the Directory (tenant) ID which is the Id of your Azure Active Directory.

Hint – It will later be used as MICROSOFT_AD_TENANT_ID in the environment variables.

Application registration overview

3) Create a new Client Secret for your app registration. The name of the secret can be chosen by you. Note down the Client Secret value once it’s created, as you won’t be able to retrieve it again.

Hint – It will later be used as <msapppassword-placeholder> and as MICROSOFT_APP_PASSWORD in the environment variables.

If you didn’t note down the Client Secret value, you can delete the Secret and create a new one. Please ensure that if you delete or update your Secret at a later point in time, to also replace it in your environment variables.

Application registration – Client Secret

4) Expose an API for your new application registration by clicking on Set in the respective sub-menu.

Application registration – Expose an API

The syntax for the Application ID URI is the following.

Syntax:
api://<domain-placeholder>/botid-<msappid-placeholder>

Sample:
api://sap-dev-teams.cfapps.eu20.hana.ondemand.com/botid-abcd246f-…-ac6ab1234

This format allows you to use your app registration for a Microsoft Teams chat bot and standalone page extension scenario. The different placeholders are explained in detail below.

Application registration – Application ID URI

The <msappid-placeholder> is the Client Id of your current application registration, noted down in step 2 of the current blog post.

The <domain-placeholder> is the future runtime URL of your extension application in the SAP BTP environment, which is based on the following syntax (if not using a custom domain!).

Hint – The <domain-placeholder> will later be used as DOMAIN in the environment variables. So maybe it’s worth writing it down somewhere.

Syntax:
<application name>.cfapps.<BTP region>.hana.ondemand.com

Sample:
sap-dev-teams.cfapps.eu20.hana.ondemand.com

The <application name> should be in sync with the app name you’ve chosen in the fourth part of this blog post series (click here). It consists of your SAP BTP subaccount subdomain, your Cloud Foundry Space, and the application identifier. The <BTP region> is the SAP BTP region in which your extension application will be hosted like eu10 or us20.

5) Add a new custom scope called access_as_user to your exposed API. The prefix based on your Application ID URI will be added automatically. Make sure that Admins and users can consent. Add some descriptive text before saving.

Admin consent display name: Teams can access the user’s profile
Admin consent description: Allows Teams to call the app’s web APIs as the current user.
User consent display name: Teams can access your user profile and make requests on your behalf
User consent description: Enable Teams to call this app’s APIs with the same rights that you have

Hint – The full custom scope name (incl. the api://… prefix) will later be used as BTP_SCOPES in the environment variables. So, save yourself some time and note it down right away.

Application registration – Custom scope definition

The custom scope is required, as it allows Microsoft Teams to interact with Azure Active Directory on-behalf-of the current Microsoft Teams user. Therefore, the application registration IDs of Microsoft Teams will be assigned this scope in the next step.

6) Add the following IDs of the two official Microsoft Teams clients (Desktop and Web client) as Authorized Clients to your app registration and assign them the custom scope you just created.

• 1fec8e78-bce4-4aaf-ab1b-5451cc387264 (Teams mobile or desktop application)
• 5e3ce6c0-2b1f-4285-8d4b-75ee78787346 (Teams web application)

Application registration – Add Microsoft Teams clients

7) Configure your app registration to accept access tokens of version 2 only. This must be done manually in the Manifest sub-menu of your app registration. Don’t forget to Save this change.

Application registration – Set access token version

8) Configure the Redirect URIs for your app registration. Please add the following Redirect URIs of type Web.

• https://<domain-placeholder>/botid-<msappid-placeholder>
• https://token.botframework.com/.auth/web/redirect

Hint – In the meantime you should know the values of the respective placeholders by heart. If not, please check the previous steps to find the required parameter values.

Application registration – Define the Redirect URIs

9) Activate the check-boxes for Access tokens and ID tokens to be issued for your app registration by the authorization endpoints.

Application registration – Set the issued tokens

10) Configure the following Microsoft Graph API permissions for your application registration. These permissions are required to retrieve information like the user’s name or his photo from Microsoft Graph.

Application registration – Define Microsoft Graph permissions

The following table shows the list of required Microsoft Graph permissions.

Permission	Type	Description
Basic
email	Delegated	View users’ email address
offline_access	Delegated	Maintain access to data you have given it access to
openid	Delegated	Sign users in
profile	Delegated	View users’ basic profile
User.Read	Delegated	Sign in and read user profile
Extended
User.Read.All	Application	Read all users’ full profile

Important: The User.Read.All on Application level is required for two purposes.

1. To send Notifications to users. As SAP SuccessFactors events only contain the email address of sender and recipient, the Active Directory User GUIDs need to be read via Microsoft Graph. These GUIDs are essential to send messages to an existing conversation reference. At this point of time, no user context is available to make use of delegate permissions for reading the required Microsoft Graph data.
2. To retrieve user data in a tab scenario. Within a tab (based on Adaptive Cards), only one OAuth Connection (you will create those later) can be used at a time. As for SAP BTP requests we have no other choice than using an OAuth Connection, Microsoft Graph data must be acquired using application privileges.

More details are available in the Microsoft Documentation Use SSO Authentication.

11) Grant admin consent for the selected API permissions. This is required, as the sample application has not been developed to its full extent, in which a user could grant the respective permissions him- or herself. For the User.Read.All permission on application level, an admin consent is required by anyway.

Application registration – Give admin consent

Enable the SAP BTP integration for your application

Once you’ve configured the application registration for your extension app, you need to follow the three simple steps below, to enable the required integration with SAP BTP (using the trust between SAP BTP and Azure Active Directory) and to make use of Principal Propagation.

In a nutshell, the application registration of your extension app, needs to be added to the authorized clients of the app registration, which was created when you established the trust between your Active Directory and SAP BTP. This client relationship will allow your extension app to request a valid SAML assertion which can be used to access your SAP BTP services.

1) Go to the App registrations sub-menu of your Azure Active Directory. Here look for the app registration with the name of the Enterprise application, which you configured when establishing the trust between Azure Active Directory and SAP BTP.

Hint – Make sure you go to the App registrations and not the Enterprise applications sub-menu!

App registration created during trust configuration

2) Switch to the Expose an API section and add a new authorized client application.

Add your extension application as authorized client

3) This is the place where you need to add the Client Id of the application registration that you created for your Microsoft Teams extension app. You’ve noted down this Client Id at the beginning of this blog post.

Add the user_impersonation scope to your client

Add the corresponding Client Id and assign the user_impersonation scope by selecting the checkbox. This scope should be there by default and will allow your extension app to use the application registration (created by the SAP BTP – Active Directory trust setup), on-behalf-of the signed-in user.

Azure Bot Service

In this step, you will create a new instance of the Azure Bot Service. This service connects your bot implementation (running in your SAP BTP Cloud Foundry environment) with the actual Microsoft Teams client apps. Furthermore, it offers some standard features for convenient bot usage.

Hint – Although the Azure Bot Service offers a free tier plan, it cannot be created without an Azure subscription. If you don’t have an Azure subscription yet, you can apply for a free trial subscription. Please find the respective links and information in the fourth blog post (click here).

1) Create a new Azure Bot Service instance within the Azure Portal. You can find the Bot Services by typing Bot Services into the search bar.

Create an Azure Bot Service instance

2) Select Azure Bot as the type of your bot. You might need to scroll down and click Load more to see the Azure Bot at the end of the list.

Azure Bot Service – Bot type Azure Bot

3) You need to configure some settings of your Azure Bot instance before the bot can be created.

Azure Bot Service – Configure your instance

For instance, first choose a meaningful name (e.g., Leave-Request-Bot) for your Azure Bot before assigning it to a subscription and resource group. We recommend to assign all services of this scenario to the same resource group. Select the Free pricing tier for this demo scenario by clicking on Change.

Azure Bot Service – Free pricing tier

When creating this demo scenario, we used Multi Tenant as app type, as our Azure Bot was create in another Azure directory as the directory in which our application registration was defined. For the purpose of evaluation, Multi Tenant should also be fine for you, whereas in a productive environment, this might be different.

Important – Assign the Azure Bot to the existing application registration which you’ve just created. The required Client Id and Client Secret can be found in the first steps of the current blog post. Do not create a new application registration, as this would mean you have to configure all settings (Permissions, API, Redirect URLs, …) once again.

Click on Review + create to review and create your Azure Bot instance.

4) Add Microsoft Teams to the connected channels. Once the Azure Bot is created, this can be done from the Channels sub-menu and should be self-explanatory. Make sure, the Health status of your channel shows Healthy like in the following screenshot.

Azure Bot Service – Microsoft Teams channel

5) Switch to the Configuration sub-menu of your Azure Bot. Setup the messaging endpoint which has to following syntax.

Syntax:
https://<domain-placeholder>/api/messages

Sample: 
https://sap-dev-teams.cfapps.eu20.hana.ondemand.com/api/messages

The <domain-placeholder> is the runtime URL of your extension app in the SAP BTP environment. You’ve noted down the placeholder value in the first part of the current blog post.

Azure Bot Service – Messaging endpoint

6) To enable easy communication between your bot implementation and Microsoft Graph as well as SAP BTP services, you have to configure so-called OAuth Connections. These connections will allow you to obtain OAuth tokens with scopes for Microsoft Graph or for an exchange against a SAML assertion for SAP BTP access.

Start with the connection for Microsoft Graph. Click on Add OAuth Connection Settings in the Configuration sub-menu of your Azure Bot and provide the following details:

• Name: GraphConnection
• Service Provider: Azure Active Directory v2
• Client id: Client Id of your application registration (see first part of the blog post)
• Client secret: Client Secret of your application registration (see first part of the blog post)
• Token Exchange URL: api://<domain-placeholder>/botid-<msappid-placeholder>
• Tenant ID: Common
• Scopes: email,offline_access,openid,profile,User.Read (comma separated)

<domain-placeholder>: See further information in step 4 of the current blog post
<msappid-placholder>: The Client ID of your application registration

Azure Bot service – OAuth Connection for Microsoft Graph

7) For the communication between your bot implementation and SAP BTP, an additional OAuth Connection is required. Please use the following connection details to create it:

• Name: BTPConnection
• Service Provider: Azure Active Directory v2
• Client id: Client Id of your application registration
• Client secret: Client Secret of your application registration
• Token Exchange URL: api://<domain-placeholder>/botid-<msappid-placeholder>
• Tenant ID: Common
• Scopes: api://<domain-placeholder>/botid-<msappid-placeholder>/access_as_user

8) You can test your OAuth Connections by clicking on Test Connection. If requested, login with your Active Directory user and check if you can request an OAuth token.

Hint – You can use an online service or an npm package of your choice to decode and check whether the required scopes are included in the token (Microsoft Graph scopes or your custom access_as_user scope).

OAuth Connection test

Azure Storage account

Create a new Azure Storage account. This Storage account will be used to store so-called conversation references. These references are required to send notifications to the correct chat bot conversation. The Microsoft Bot Framework SDK provides a convenient integration between your bot implementation and the Azure Storage account.

Important – This is a paid service, meaning there is no always-free pricing tier available for this Azure service. Using an Azure trial subscription, you should be eligible to use this service 12 months for free before paying any service fee. Please double check which configuration type is included in the free trial and (as usually) always monitor your Azure subscription costs.

1) You can find the Azure Storage accounts service using the search bar and searching for Storage accounts.

Azure Storage accounts

2) Create a new instance, providing a subscription and a resource group, as well as a unique Azure Storage account name that can be chosen by you. You might need to add further characters if your preferred name is already taken across the Azure landscape.

Make sure you’re selecting the redundancy level based on your purposes (development, productive app, etc.). For testing purposes, the redundancy is probably less important and you can stay with the Local-redundancy storage (LRS) option.

Sample Azure Storage account configuration

3) Make sure the blob public access is disabled in the Advanced tab before clicking on Review + create to create your Azure Storage account instance.

Hint – Feel free to check the other configuration tabs to e.g., restrict access to your Azure Storage account to certain IP addresses like SAP BTP region specific values.

Disable blob public access

4) Add a container to your Azure Storage account and give it a name of your choice (e.g., botstorage). It will store the conversation references of your chat bot. You can maintain your containers in the Containers sub-menu.

Hint – The container name you set here will later be used as MICROSOFT_BLOB_CONTAINER_NAME in the environment variables.

Create a container in your Azure Storage account

Set your container name

5) Note down one of the available connection strings from the Access keys sub-menu of your Azure Storage account. Click on the respective toggle button to show or hide your key values.

Hint – This connection string will later be used as  MICROSOFT_BLOB_CONNECTION_STRING in the environment variables.

Find and note down one of the connection strings

More information is available in the Microsoft Documentation Write directly to storage.

Microsoft Teams license

To use Microsoft Teams, you must assign an appropriate license to your Azure Active Directory users. When developing this sample scenario, the Microsoft Teams Exploratory license has been used. You can find more information and eligibility requirements to use this free license in the official Microsoft documentation (click here).

In the following, I will explain you how to activate this license for your own Azure Active Directory (if eligible). If you’ve already got an existing Microsoft Teams license, make sure you assign it to your test users accordingly.

1) The Microsoft Teams Exploratory license can usually be self-assigned by one of your Azure Active Directory users. To do so, one of your Active Directory users must login to Microsoft Teams using e.g., the Microsoft Teams Web client (click here).

2) Once the first user tries to use Microsoft Teams using its Azure Active Directory credentials, the following message will appear. Checking the URL, you can see that a license for Microsoft Teams is missing and whether or not, you’re eligible for a trial license.

Microsoft Teams missing license notification

3) Click on Sign up for Teams to get more information on available Microsoft Teams licenses. Meanwhile and if eligible, in the background, the assignment of the Exploratory license should start automatically.

4) Wait a few seconds before reloading the current page. You should now be able to login to Microsoft Teams with the same user that triggered to automated license assignment. If not, please logout and login again.

Hint – At the same time, the Active Directory administrators will receive an e-mail information, that the Exploratory license has been activated for the organization.

Microsoft Teams Exploratory license information

5) Once the Exploratory license is activated for your organization, you can assign it to other users in the Azure Portal. Therefore, login as a (user) administrator to your Azure Active Directory (https://portal.azure.com/).

6) Select the user you want to assign the Microsoft Teams Exploratory license and switch to the Licenses sub-menu to start an assignment.

Hint – Depending on your Azure Active Directory subscription type this should also be possible via a user group license assignment (click here). In a free Active Directory please assign the license to each test user manually.

Microsoft Teams license assignment

7) You can now assign the Microsoft Teams Exploratory license to your user. In our development landscape, we disabled the Exchange Online feature. Click on Save to apply the changes.

Microsoft Teams Exploratory license assignment

8) If you’re facing an error messages concerning the location in the previous step, make sure your user is assigned to a usage location in its Active Directory profile.

Hint – I recommend to add a profile picture for your test user in the same step (if not done yet). Things will look much nicer when testing the extension application at a later point in time!

Azure Active Directory – Usage location

9) All Microsoft Teams Exploratory license users should now be able to access Microsoft Teams using the Web or Desktop client. If not, try to logout and login again. That should refresh your permissions.

What’s next?

Lean back and relax! You’re done for today and successfully configured the remaining requirements in your Microsoft Azure landscape. Your bot is now able to communicate with Microsoft Teams using the Azure Bot Service and has a data store to hold important conversation references.

Furthermore, your app is now capable of exchanging dedicated Azure Active Directory tokens to valid SAML assertions (used for SAP BTP interaction) and to access required Microsoft Graph data. Finally, your test users have been assigned a Microsoft Teams license to allow testing in the next part of the blog post series.

In the upcoming and final technical blog post, you will gather all your configuration details and provide the required environment variables to your extension application. This will allow a swift deployment of the application to your SAP Business Technology Platform and an easy upload to the Microsoft Teams client.

Stay curious!