Account linking with Microsoft Teams single sign-on

Have you had trouble understanding how to use single sign-on (SSO)? Are you trying to link your identity system with Teams SSO for your Teams app? In this article, learn what Teams single sign-on means and take a look at a sample we’ve built to help you use Teams SSO with your Identity Provider (IDP).

Before we dive into these details, it’s important to understand how to link user accounts between Teams and your app and Teams SSO. The following resources are recommended to review:

You can also learn with this series of hands-on labs in Microsoft Teams App Camp, which leads you through the experience of turning a simple web application into a Microsoft Teams application. As part of these labs, an account linking strategy is used to allow users to log in with Azure Active Directory SSO and still maintain user profiles and authorization from the original identity provider.

Teams SSO Overview

In short, Teams SSO is an identification model that enables users to login into a Microsoft Teams application with the same credentials they used when they signed into Microsoft Teams. The process is completely silent unless the application needs to ask the user to grant additional permissions. This diagram helps illustrate the underlying mechanism.

For a longer explanation of SSO, please refer to this article: Let’s decode: Single Sign-on in Microsoft Teams tabs – Microsoft 365 Developer Blog and follow this Teams SSO tutorial on Microsoft Learn: Microsoft Teams – Authentication and Single Sign-on – Learn | Microsoft Docs

What are the challenges?

Teams SSO offers a seamless experience for partners to build auth inside of Teams. However, Teams SSO can be difficult to implement when you (the person building the Teams app) need to link user accounts between Teams and your app’s identity systems.

To get around this, we typically see partners try to use email addresses to match up user identities in their different systems. However, that generates several problems.

Even if the emails are the same, there are a few problems. First, emails and User Principal Names (UPNs) can sometimes change. Second, most likely, the identity framework you’ve chosen won’t accept a simple email mapping and provide the user’s access tokens in their system. These access tokens are required because they are used to get permissions on the user’s behalf and are extremely important to keep secure. This path would also require you to change your own security architecture to allow special requests from your Teams apps.

This is especially difficult if the user’s email in Teams is different than their email in your system. For example, the user’s AAD email could be: john@contoso.com, but the email that is registered with you is john@gmail.com or even johnmatthews@contoso.com. In both of these examples, the emails don’t match up. The personal email address issue occurs frequently with apps that exist outside of enterprise scope.

There’s an elegant solution to this problem.

An elegant solution

Description

Get the user’s AAD access token – which can be done with a simple call (the beauty of SSO – review SSO Overview if this is unclear)
Ask the user to sign into your chosen system or Identity Provider (IDP)
Retrieve the access that your system or the Identity Provider provides
Store that access token in a table associated with the user’s AAD identity

Therefore, there are four parts to this solution:

Logic to get a user’s Teams identity
UI to prompt user to login to your app
Logic to connect the user information from your IDP system to a user’s identity in Teams
Table that contains: User’s Teams identity (GUID/UUID) and the user’s access token from your IDP

Now, whenever your Teams app needs to make a call, it can:

View the user’s identity
Check the table for the user’s IDP access token
Call your app using that token

Next Steps

This content can help you get started with Teams SSO if you are new to it:

Try it today! Here is a sample of this solution to help you understand it better and get started
Try these hands-on labs in which you can migrate a web application with a non-Azure AD identity system to use Azure AD SSO with an account linking strategy. https://aka.ms/app-camp-account-linking

Have fun!