Create an App Registration in Azure AD

Azure AD is a subsection of the Microsoft Azure Portal, therefore you need to have an account with appropriate rights. If you don't already have an account, you can create one for free with some free resources during the first 30 days. 

Log on to the AAD Portal and open the Azure Active Directory.

Then open App registrations in the side panel.

Click New registration

And add the following information.

The Name will be the name that is displayed to the user in Teams.

The Account type can be single or multitenant depending on your Azure AD structure.

The Redirect URI always needs to be "https://token.botframework.com/.auth/web/redirect" to make sure authentication requests get authenticated by Microsoft.

Click Register.

The App Registration overview page shows the Application (client) ID that is referred by several different names throughout the Microsoft platforms. We will refer to it by the name Client ID so save it to the text file for later use.

The Directory (tenant) ID is required later when using single tenant app registrations, so save it to the text file as Tenant ID. When building a multi-tenant app registration, this is not required.

We will now cover all menus from the side bar that need to be configured.

Authentication Settings

The Redirect URI needs to be “https://token.botframework.com/.auth/web/redirect”.

Change the Front-channel logout URL to the Endpoint URL of the Azure Bot Services endpoint we previously created.

Make sure to check both checkboxes for Access tokens and ID tokens as both are mandatory for SSO.

The Account Type should already be set to the type we picked earlier.

Certificates & Secrets Settings

For SSO, we need to create a secret. Click New client secret to create a secret and copy the Value using the copy icon, then save it to the text file. We will later refer to it as the Client Secret.

This is your only chance to save it as it won’t be readable afterwards, so if you lose it you need to create a new secret later.

API Permissions Settings

Please note, SSO enables us to receive a token that can be used with the Graph API to trigger a lot of different services or retrieve data, e.g., reading the user’s name or his emails.

Now we need to specify all permissions that are mandatory for executing these tasks. There are two different types of permissions available:

1. User approved permissions
2. Admin approved permissions

Depending on the configured rights in your Microsoft Teams organization and Azure, it might happen that admin approval is required even though the selected rights are marked as if they don’t require admin approval. This you will most likely occur if you request permissions from a user and when giving consent, a popup menu states that the app needs to be approved by an administrator.

Admins can then approve these requests here: https://aad.portal.azure.com/#blade/Microsoft_AAD_IAM/StartboardApplicationsMenuBlade/AccessRequests

It might also be mandatory to verify a publisher domain and create an MPN (Microsoft Partner Center) ID. This can be done in the Branding section of the sidebar.

User approved permissions include the rights to retrieve the username and job title. For these, a single user approval is sufficient.

Admin approved permissions include higher rights that might have an impact on your organization.

In this tutorial, we only focus on user approved permissions.

Click Add a permission to add a new one.

Click Microsoft Graph as this API can be used to call all APIs that are of interest for us.

For SSO, we need to have Delegated permissions.

Now we select all permissions that we want to grant our SSO bot consent for. Better save the names of the permissions as we need them later. We will refer to them as Permissions. Don’t get confused by the non-conformant naming schema, we always need the name string, such as “email” or “openid”.

Make sure to check openid as it’s mandatory for SSO authentication. Click Add permissions.

Now click the Grant admin consent for ... button to approve the permissions, they should now show a green checkmark.

Expose an API Settings

At first, we need to modify the Application ID URI. This value must be “api://botid-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" where the x's are your Client ID we copied previously.

Now click Add a scope.

The Scope name can be chosen freely, but it’s important to toggle so Admins and users can consent. Fill out all other mandatory fields, they will be displayed when adding the Teams app to Teams.

Then click Add scope and then Add a client application twice.

We need to add two different Client IDs now:

5e3ce6c0-2b1f-4285-8d4b-75ee78787346 (required for MS Teams Web Client)

1fec8e78-bce4-4aaf-ab1b-5451cc387264 (required for MS Teams Mobile & Desktop Client)

 

It should now look like this:

Manifest Settings

The Manifest is the configuration file that automatically gets created and reflects all changes that you did to the configuration. Microsoft has reduced the number of possible settings in the menus; therefore, we need to modify some values in this large JSON object. Don’t forget to press the Save button above after completing the changes.

 

Modify these settings:

AccessTokenAcceptedVersion: null --> 2

Oauth2RequirePostResponse: false --> true

SignInUrl: null --> The previously copied Endpoint URL from Cognigy AI

This concludes the App registration.