>> Hi, I'm Joshua Trick and I'm
a software developer for Microsoft teams.
I'm here to talk today about
authentication in apps for Microsoft Teams.
To begin with, I would just like to say
for the examples and demos you're about to see,
all of this code can be found at
our GitHub repo seen here on
the screen and can be
downloaded and run locally yourself.
To begin with, let's talk about
a high-level overview of how
authentication works within the Teams platform.
Whether you're talking about a Tab, a Bot,
or a Messaging Extension,
all of the various flows have a similar pattern.
The Tab, Bot, or Messaging Extension, using the SDKs,
will tell the Team's platform to open a popup
starting with a page that you own on your domain.
That start page will then
redirect to the identity provider,
the authentication host that
you're trying to have your user log into.
Once that authentication is complete,
that page will redirect to a page you own
again with the same domain
that you own from the start page.
This ''Redirect'' or ''End'' page
will use the SDK and notify
Teams of a success or
failure status which will
then give information back to your app.
Let's look at authentication in tabs.
With that general pattern,
the only differences between tabs and
other flows are the starts and the ends.
For the basic tab flow,
your tab content or config
page will present the user with
a button that they will click on to
notify Teams to open the authentication popup.
That popup, just like with the overview,
will first open a page on a domain you own,
that page will then redirect to the Identity Provider,
which will then, upon authentication,
redirect back to a page
on your domain that you own so that you
can use the JavaScript SDK
to notify Teams of success or failure.
Specifically for the tab flow,
that success or failure should get
the end page to either set a cookie or store
the token and information in the local storage so that
your content or config page
can use it for later processing.
So, let's see what this would look
like in a real world situation.
So for this tab auth flow as mentioned,
we have our content URL,
and we have our button which is going to tell,
using the JavaScript SDK,
Teams that it's time to open the authentication popup.
With that call to authenticate, we can click,
come to the start page,
and redirect to our AAD login page.
With that login page,
I can log in.
And now, when I redirect after this login,
I will redirect back to the page that
I own which will tell Teams to
close this popup and send
that information down to the content page.
Because that authentication page closed,
it notified our content page that
the authentication was complete and it was time to
take the token and find
the profile for this user
which is the person that just logged in.
Now, let's look at the code
that made all of that possible.
So, for the code that made that possible,
we first start with our content page
which is hosted with the simple HBS file.
The first step that page does is import
the JavaScript SDK for Teams.
Within the JavaScript, it then
initializes the Microsoft Teams object,
and the button ''Callback'' is linked to
the login URL command which calls the MicrosoftTeams.
authentication.authenticate call, which is
actually the call that tells Teams to open the popup.
In order to do that, we first have to give it a URL,
and then we actually give it
success callbacks and failures based
upon what that popup flow notifies us in return.
For us that success callback is simply going to take,
get the token out of
local storage and then
get the user's profile with that token.
So when the user clicks on that button,
and the authentication popup is created,
that popup is hosted for us by this URL,
which is the Simple Start page.
The Simple Start page simply navigates and
redirects the page to the login for AAD.
That login for AAD, as we saw,
allows the user to login
and then upon completion of that,
redirects to our Simple End file.
Here, we import the SDK,
initialize the Microsoft Teams object,
and then based upon the parameters we received,
we can either notify of failure or success.
For us, because we know we authenticated successfully,
we're going to go down the successful route
by taking and storing in local storage the
token and then notifying Teams of
success with the key
to get that token out of the local storage.
This then can be caught again
back on our Content Page in our success callback.
Now let's take a look at authentication in bots.
For the basic bot login,
the user will indicate to
the bot that it's time to login,
and the bot will respond to
the button of the sign in action type.
The user will then click the ;;Sign in
action type'' which will tell
the Teams platform to open
another authentication popup
similar to the one in the tab.
That will open onto
the start page for a domain that you own.
That start page will redirect to the identity provider.
And after authentication is completed,
we'll redirect back to
the end page on a domain that you own.
That end page's job is to,
using the SDK, notify
the Team's platform of success or failure.
Different than the tab authentication flow,
this success or failure will actually
get the Team's platform to send
an invoke message of a specific type
back to your bot so that it can do what it needs to.
So, let's see what that looks like within Teams.
For our bot demo,
we have our authentication bot which actually
provides multiple logins and identity providers.
For this scenario, we're going to use
the LinkedIn example to show that
it's just as easy to have
a third party provider as it is for AAD.
So, for our LinkedIn flow,
I'm going to sign in.
And for that authentication flow
with the bot is now done is sent,
a ''Sign in'' button that when I click on it,
it's going to tell the Teams platform to
open a popup for the authentication.
So I've now open to first
my domain page which
redirected to the LinkedIn login page.
And now, if I log in here,
upon doing this successfully,
it's going to redirect back to my domain,
notify success, and tell
the bot that I logged in successfully.
With that token, I can now have the bot
get my profile and shows my information.
Let's go ahead and take a look at
the code that made that possible.
In order to kick off the login flow for the bot,
the user will send the sign in command
which will fall into the Handle Login Command.
That command will first create a sign in URL and
then return a card with the sign in
action opening to that URL.
That sign in action,
when the user clicks on it,
will notify the Teams platform to
open the popup to that page.
That page, which is rendered with auth-start,
will take the context and
redirect to the appropriate identity provider.
That identity provider will allow the user to log in,
send the authentication information
to the back end of the bot,
and the back end of the bot will store
the information and send in
the oauth-callback-success handlebars page
a verification code
in order to verify that the user that signed
in is actually the user that's talking to this bot.
For the oauth-callback-success handlebars page,
the first thing will do is import the JavaScript SDK,
initialize the Microsoft Team's object,
and then notify success with that verification code.
What this call of notify success to
the Microsoft Teams object in the bot context will do,
is tell the Microsoft Teams platform to send
a special invoke message with the sign in
type with this verification code back to the bot.
When the bot receives this invoke message,
it will then get navigated
to the Handle Login Callback Page.
This Handle Login Callback Page,
upon receiving that invoke message,
will take that verification code
and validate that the currently logged
in user and the user that's
talking to the bot are the same person.
This then will allow the bot to safely use this
token in order to get
information like the LinkedIn profile.
Having seen those flows,
there are a few things to remember.
First, the popup flow has to start on a page,
on a domain that you own and
end on that end page with that same domain.
So, as we see in this example,
if you start the popup flow with myapp.com.
you have to end the flow on myapp.com.
in order for Teams to know to properly close the popup.
Next, in order for
the Teams platform to allow that popup to be opened,
you need to make sure that you add your domain that
you're wanting to open in the manifest,
in the valid domains list.
For AAD specific authentication,
for the various types of users we
can have within the Teams platform,
make sure you use the tenant ID specific
login URL rather than the common URL.
This tenant ID can be found either in the tab context in
the TID parameter or in the
channelData.Tenant.id section of a bot message.
We get asked a lot how a Tab, a Bot,
and a Compose Extension can share state and
which IDs will be the
same between the different contexts.
The AAD object id or user ID will be the idea that
you can use in
all the contexts to
know that you're talking to the same user.
In order to do these login flows,
the information needed for
the bot flow is actually
located within the bot's message,
in either the AAD Object ID or the Tenant ID field.
And finally, for these and other resources,
you can navigate to these URL's to
find either the sample we did hear,
various other samples, or
a Microsoft Teams documentation. Thank you.