Create a Microsoft Teams App

There are several possible ways how to create a new Teams App. Here we will use the Apps Developer Portal.

Browse to https://dev.teams.microsoft.com/apps, and click Create your first app or New app.

Basic Information Section

Fill all fields that are marked as required. For the Application (client) ID we enter the Client ID we copied previously. If you have permissions with admin consent, you need to add a Microsoft Partner Network ID as well.

App Features Section

Now we need to specify the features our Bot will use. Not all of them will support SSO or might require additional or different configuration and there’s no proper documentation from Microsoft so this documentation is matched for Bot SSO solely. Click Bot.

Enter the Client ID as the bot ID and select Upload and download files. There is a strange bug that prevents you from sending attachments to other users if you don’t set it, so it needs to be set, even when no file handling is planned.

Click Save.

Single sign-on Section

Here we need to add “api://botid-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx” where X is the previously copied Client ID, then save it.

Domains Section

Here we need to add at least two domains, token.botframework.com for token authentication as well as the domain where the endpoint is hosted.

Publish to the Teams store Section

This page gives an overview if everything is fine. If there are errors, make sure to resolve them. After fixing all errors, click Download app package to receive a zip file with the Teams app.

Package Fixing

We got the package but unfortunately, we still need some small final adjustments before we can publish it.

1. Unzip the content to a folder, you should get two images and a manifest.json file. Open the file in a code editor such as Visual Studio Code.
2. Around line 6 there’s a key packageName, change the value to a different value than com.package.name as SSO won’t work otherwise.
3. Around line 21 there’s a scopes array within the bots array. Add a string “personal” to it.
4. Add a key with your domains to the top level, e.g. "validDomains": ["token.botframework.com", "mydomain.com"]
5. Add a key to the top level "permissions": ["identity", "messageTeamMembers"]

Your manifest should now look like this. Save it.

Now select the modified manifest.json and the two other files and create a new .zip folder from it. Make sure it’s just these files and not a folder in the package above.

Upload the Teams App

Open your Teams client or https://teams.microsoft.com and open “Apps” on the bottom left.

Click Upload a custom app and choose the new created package.

You will see a summary of your app and its permissions and hopefully an Add button.

Click Add and the bot should now become a contact you can chat with. If you receive an error message that something went wrong, open the browser debugging tools and check if you get further information. If not, you need to check all previous steps if they were done correctly.

If successfully added, all messages to the Chatbot should now be delivered to the flow that is linked in the Azure Bot Services endpoint. Now we need to apply some logic to the flow to use SSO.