Single sign-on demo for Microsoft Teams apps using OAuth
In this demo, we will show you how to authorize a user to access resources through a Microsoft Teams app with a bot. We will use Azure Active Directory for OAuth provider and Microsoft Graph for the protected resources.
After sign-in, this demo will keep OAuth token inside the Teams tab, and also send it to the bot via Web Chat backchannel. Because both web page and bot need to hold a single OAuth token, we are unable to use OAuth card in this demo.
When dealing with personal data, please respect user privacy. Follow platform guidelines and post your privacy statement online.
This sample is a simplified and reduced version of the sample “Single sign-on demo for enterprise apps using OAuth” and modified from “Single sign-on demo for Intranet apps using OAuth”. There are notable differences:
- In this demo, we are targeting Microsoft Teams “tab apps”, which is a set of web pages browsed through an embedded and limited web browser inside Microsoft Teams
- Tab apps are supported on desktop client only. Microsoft Teams on mobile client do not support embed content in apps and requires external apps for tab content
- OAuth sign-in popup is controlled by Microsoft Teams
- We will only allow an authenticated user access to the page and the bot
- Since we only allow authenticated access
- We no longer have UI buttons for sign-in and sign-out, and only use plain HTML instead of a React app
- We no longer send the sign-in and sign-out event activity to the bot
- We only support a single OAuth 2.0) provider; in this demo, we are using Azure Active Directory
- Azure Active Directory supports PKCE (RFC 7636), which we are using PKCE to simplify setup
- If you are using GitHub or other OAuth providers that do not support PKCE, you should use a client secret
This demo does not include any threat models and is designed for educational purposes only. When you design a production system, threat-modelling is an important task to make sure your system is secure and provide a way to quickly identify potential source of data breaches. IETF RFC 6819 and OAuth 2.0 for Browser-Based Apps is a good starting point for threat-modelling when using OAuth 2.0.
How to run locally
This demo integrates with Azure Active Directory and Microsoft Teams. You will need to set it up in order to host the demo.
- Start ngrok tunnel for Microsoft Teams app
- Clone the code
- Setup OAuth via Azure Active Directory
- Setup Azure Bot Services
- Setup a new Microsoft Teams app and install it locally
- Prepare and run the code
Start ngrok tunnel for Microsoft Teams app
Since Microsoft Teams only supports
https:// addresses, we will be using ngrok tunnel to provide a temporary HTTPS tunnel for this demo.
- Download ngrok
ngrok http 5000
- Write down the Microsoft Teams app tunnel URL in this step
- In the steps below, we will refer this URL as https://a1b2c3d4.ngrok.io/
- You should replace it with the tunnel URL you obtained from this step
Clone the code
To host this demo, you will need to clone the code and run locally.
- Clone this repository
- Create two files for environment variables,
- When Azure Active Directory completes the authorization flow, it will send the browser to this URL. This URL must be accessible by the browser from the end-user machine
- This will forward all traffic from https://a1b2c3d4.ngrok.io/api/messages to http://localhost:3978/api/messages, where your bot is listening to
Setup OAuth via Azure Active Directory
- Go to your Azure Active Directory
- Create a new application
- Select “App registrations”
- Click “New registration”
- Fill out “Name”, for example, “Web Chat SSO Sample”
- In “Redirect URI (optional)” section, add a new entry
- Select “Public client (mobile & desktop)” as type
http://a1b2c3d4.ngrok.io/api/oauth/callback as the redirect URI
- This must match
/web/.env we saved earlier
- Save the client ID
- Select “Overview”
- On the main pane, copy the content of “Application (client) ID” to
/web/.env, it should looks be a GUID
Setup Azure Bot Services
We prefer using Bot Channel Registration during development. This will help you diagnose problems locally without deploying to the server and speed up development.
Since we already setup
PROXY_BOT_URL in our web server
/web/.env in “Clone the code” step, we can reuse the same ngrok tunnel. It will forward traffic from the web server to the bot.
You can follow our instructions on how to setup a new Bot Channel Registration. Points the messaging URL to https://a1b2c3d4.ngrok.io/api/messages.
- Save the Microsoft App ID and password to
- Save the Web Chat secret to
When you are building your production bot, never expose your Web Chat or Direct Line secret to the client. Instead, you should use the secret to generate a limited token and send it to the client. For information, please refer generating a Direct Line token and Enhanced Direct Line Authentication feature.
Setup a new Microsoft Teams app and install it locally
This section is based on the Microsoft Teams article named “Add tabs to Microsoft Teams apps”.
- Install App Studio app on Microsoft Teams
- In the App Studio, switch to “Manifest editor” tab
- Click “+ Create a new app” button
- Fill out “App details” under “Details”, for example:
- For “App names”, enter “Web Chat SSO”
- Under “Identification”
- Click “Generate” button on “App ID”
- For “Package Name”, enter “com.mycompany.bot.sso”
- For “Version”, enter “1.0.0”
- Under “Descriptions”
- For both “Short description” and “Long description”, enter “Company landing page with Web Chat and Single Sign-On”
- Under “Developer information”
- For “Name”, enter “My Company”
- For “Website”, enter
- Under “App URLs”
- For “Privacy statement”, enter
- Fill out “Tabs” under “Capabilities”
- On “Add a personal tab” section, click “Add”
- For “Name”, enter “My Company”
- For “Entity ID”, enter “webchat”
- For “Content URL”, enter
- Click “Save” button
- Under “Test and distribute” of “Finish” section
- Click “Install” button
- On the “Web Chat SSO” dialog, click “Install” button again
Prepare and run the code
- Under both the
web folder, run the following:
- In Microsoft Teams, open the new app you just created in the “Setup a new Microsoft Teams app and install it locally” step
- Click “…” on the navigation bar below “Files”
- Click “Web Chat SSO”
- Click “My Company” tab
Things to try out
- When you open the tab in the app for the first time, the tab should automatically popup an Azure Active Directory sign-in dialog
- Type, “Hello” in Web Chat
- The bot should be able to identify your full name by using your access token on Microsoft Graph
/bot/ is the bot server
/web/ is the REST API for handling OAuth requests
GET /api/oauth/authorize will redirect to Azure AD OAuth authorize page at https://login.microsoftonline.com/organizations/oauth2/v2.0/authorize
GET /api/oauth/callback will handle callback from Azure AD OAuth
GET /api/directline/token will generate a new Direct Line token for the React app
- It will serve a static
- During development-time, it will also serve the bot server via
- To enable this feature, add
- This will forward all traffic from
This sample includes multiple parts:
- A basic web page that:
- Checks your access token or open a pop-up to OAuth provider if it is not present or valid
- Is integrated with Web Chat and piggybacks your OAuth access token on every user-initiated activity through
- On every message, it will extract the OAuth access token and obtain user’s full name from Microsoft Graph
- Developer understand and has hands-on experience on creating a Microsoft Teams app for tab apps
- Developer has an existing Intranet web app that uses OAuth to access protected resources
- Access token can live in browser memory but must be secured during transmit through the use of TLS
- More about security considerations can be found at IETF RFC 6749 Section 10.3
- We assume the web app can be hosted as a tab under Microsoft Teams app
- Website and bot conversation supports authenticated access only
- If the end-user is not authenticated or does not carry a valid authenticated token, a sign-in dialog will appear
- This website resembles a company landing page, in which authenticated content (e.g. vacation balance) and bot conversation is required to co-exist on the same page
- Bot will receive OAuth access token from the website
Content of the
.env files hold the environment variables critical to run the service. These are usually security-sensitive information and must not be committed to version control. Although we recommend keeping these keys in Azure Vault, for simplicity of this sample, we would keep them in
To ease the setup of this sample, here is the template of
Frequently asked questions
How can I reset my authorization?
To reset application authorization, please follow the steps below.
- On the AAD dashboard page, wait until “App permissions” loads. Here you see how many apps you have authorized
- Click “Change app permissions”
- In the “You can revoke permission for these apps” section, click the “Revoke” button below your app registration
OAuth access token vs. refresh token
To make this demo simpler, we are obtaining the access token via Authorization Code Grant flow instead of the refresh token. Access token is short-lived and considered secure to live inside the browser.
In your production scenario, you may want to obtain the refresh token with “Authorization Code Grant” flow instead of using the access token. We did not use the refresh token in this sample as it requires server-to-server communications and secured persistent storage, it would greatly increase the complexity of this demo.
To reduce complexity, this sample is limited in scope. In your production system, you should consider enhancing it and review its threat model.
- Refreshing the access token
- Using silent prompt for refreshing access token
- Some OAuth providers support
?prompt=none for refreshing access token silently through
- Using Authorization Code Grant flow with refresh token
- Save the refresh token on the server side of your web app. Never expose it to the browser or the bot
- This will also create a smooth UX by reducing the need for UI popups
- Threat model
- IETF RFC 6819 is a good starting point for threat-modelling when using OAuth 2.0
Microsoft Teams: Personal tab vs. team tab
- Personal tabs are tabs that are shown in the Microsoft Teams app only, i.e. only visible for the current user
- Team tabs are tabs that are configured on a per-conversation basis, i.e. tab will be shown in a conversation with one or more team members
Because team tabs are designed to be used collaboratively by two or more users, content shown inside the team tab should be synchronized in terms of content and interactions. For example, a tab showing Microsoft Excel web app that two or more users can collaboratively edit the content.
For content that is not designed to be used by multiple users at the same time (for example, conversation with a bot), this type of content should be limited to personal tab only to reduce confusion.