>> Hi. Welcome to Microsoft Build 2018.
I'm Jeff Sakowicz a Program Manager at Microsoft Graph.
In this video, I'll provide
a detailed look at our Permissions and Consent Model.
I'll start by explaining what
Microsoft Graph is to help give you some context.
For the rest of the video,
we'll do a deep dive into
our Permissions and Consent Model,
with a specific focus on how
they relate to Microsoft Graph.
I'll start with an overview of the model,
and then dig into some best practices
and troubleshooting tips.
So what is Microsoft Graph?
If I were to give it a textbook definition,
I'd say that it's a unified REST API,
and comprehensive developer experience,
for integrating with the data and
intelligence exposed by Microsoft services.
But what does this actually mean?
Microsoft Graph is your one stop shop for accessing data,
relationships, and insights across Microsoft 365.
It's a REST API that lets
you build rich Applications that
integrate with services used by
over 100 million active users.
These services include Azure Active Directory,
SharePoint,
OneDrive, OutLook, Teams, Intune, Windows and more.
There's also some exciting new security APIs,
and even APIs built specifically for the education space.
All in all, there are over eight trillion resources
available in Microsoft Graph.
Now let's talk about Permissions and Consent.
As I mentioned earlier, we'll be focusing on how
this model applies to Microsoft Graph,
but the concepts here are pretty generic and can be
applied to other APIs
you might be integrating with as well.
It lists the ones that use
are often common Consent framework.
Let's start by going over some of the terminology.
First we have the client,
which is the application that is
requesting access to data.
This data will be exposed by a resource,
which is generally a web API, like Microsoft Graph.
This resource will also expose a number of permissions,
which grant the client the ability to
perform some action, on some data.
An example of this is the ability to
reuse OneDrive files through Microsoft Graph.
These permissions to access data are not something
the Application developer can just obtain on their own.
They need to get consent
from the owner of the data first.
This usually happens through a consent prompt,
where a user will be asked to grant the client
access to some data exposed by the resource.
When a user clicks "Yes" or "Accept" on the prompt,
this results in a consent grant being recorded.
Sometimes it's performed by an administrator,
either when the App is requesting
admin restricted permissions that
only they can consent to,
or when an admin wants to consent on
behalf of the entire organization.
There are two main permissions scenarios.
The first is where the App is getting
access on behalf of one or more users.
This is usually the case for Mobile,
Web or Single page Apps.
These Apps generally use delegated permissions,
which also might be referred to as Apps user permissions,
scopes, or simply user permissions
depending on who you ask.
Users can usually consent to
delegated permissions that grant
access to their own data,
but admins will need to consent for
higher privilege delegated permissions.
Admins can also consent to
delegated permissions on behalf
of the entire organization.
When working with delegated permissions,
the effective permissions, or
what the application can actually do,
are calculated by taking the intersection of what
the application has been granted by a consent,
and the permissions that the user
has in the underlying system.
This prevents against any elevation of privilege.
For example, if an App gets consent to do full
[inaudible] on all users across an entire organization,
but it's making calls on behalf of
a non admin user who cannot normally delete users,
the App won't be able to delete any users.
It would only be able to do so if
an admin user has signed into the App,
and the act is acting on behalf of that admin.
The other scenario is the case where
the Application is getting access as itself,
or in other words, as a service.
Apps that operate purely in the background,
otherwise known as Daemon Apps,
fall into this category,
along with other highly trusted subsystems.
These types of Apps will request Application permissions,
and are also known as S2S permissions,
or App only permissions.
Only administrators can consent
to most Application permissions.
The effective permissions are exactly what
the Application has been consented to do,
since there is no signed in
user present for the App to act on behalf of.
Most permissions Microsoft Graph exposes
are formatted with a resource prefix,
which represents the target entity that
the app is requesting permissions to access.
Next comes the action portion,
which usually indicates whether the App is
requesting read or read write privileges,
although there are some exceptions.
Finally, there's an optional suffix,
that indicates the scope of the permission being used,
not to be confused with
our scopes or delegated permissions.
Usually, this will either be.All,
indicating the permission is used to request access to
all entities of a given class
across an entire organization,
or not present at all,
which infers the permission is
specifically targeted to the
signed in user or there
are some exceptions here as well too.
A few examples of
delegated permissions include User.Read,
which is a permission that allows the App
to sign the user in and read their profile,
and notes that read write,
which is a permission that allows the App to read and
write all of the signed in users OneNote notebooks.
Files that read Write.All is an example
of a highly privileged application permission,
which allows an App to do full crowd on
all files across the organization
without a signed in user.
This is a powerful permission
that requires administrator consent,
and this sort of thing should only be
requested when absolutely necessary.
It's important to understand what permissions are
right for your scenario before requesting them.
So, be sure to check out our documentation.
There's a dedicated article that guides
you through selecting permissions,
and each one of our API
reference pages will also tell you
what specific permissions are required to call that API.
Now, let's talk about when
consent is actually prompted for.
Usually, this happens automatically.the
first time someone uses an App,
that requires permissions to access
resources that are protected via a worth.
This can also happen if the App is
coded to explicitly prompt for consent,
if the permissions the App is
requesting access to have changed,
if the user revoked
consent and want to use the App again,
or if the App is using incremental consent
to ask for some permissions up front and more later.
So, this is not always unexpected.
Speaking of Incremental consent,
it's important to know what this is,
and how it relates to a few other flavors of consent.
Static and dynamic.
Static consent is the term used for the scenario,
where the permissions in the consent prompt come from
a pre-configured list that was
specified by the developer upfront.
Static permissions are configured,
by either selecting certain permissions
in the App registration portal,
or by specifying them manually in
the required resource access section of the App manifest.
Static consent is the only option
when working with the V1 endpoint,
there is just a single set of
permissions that will be prompted
for every time the user needs to ask for consent in V1.
In the V2 endpoint,
dynamic and incremental permissions
are an option as well.
Dynamic permissions are used in
a scenario where the Application
specifies which permissions it's
requesting directly in the call it makes,
to the authorized endpoint.
These permissions are usually
specified in the code of the App as well,
and this is how it is in most of our samples.
There's a special case to be aware
of where the.default scope can be used.
This tells the authorized endpoint to look at the list of
static permissions in required resource access
or were specified in the portal even though
the app is using the V2 flow that is normally dynamic.
Incremental consent is a subset of dynamic consent,
this is where the application asks for some base set up
permissions up front and then
asks for more later as needed.
This is really useful for
apps that require a small handful of
permissions for their basic level of
functionality and then need more later,
for optional features or capabilities
that a user might not use right away or not use at all.
All right, so now let's move on
to some best practices in troubleshooting.
First things first, always
abide by the principle of least privilege.
This means that you should only
request permissions that are
absolutely necessary and only
at the moment when you need them.
Remember, that you're asking for permission to
access sensitive customer data here.
In general, it's really
important to be thoughtful when you
configure your app especially
around consent and permissions.
This can improve your apps adoption by customers,
and It can also help tighten up
your security posture in case something goes wrong.
For example, in addition to a body Malys privilege,
it's important to choose between delegated or
application permissions based on your scenario.
Putting yourself in the customer's shoes is
also very important especially when you're
building a multi-tenant app that will be available to
many users across many organizations.
Here, you need to think about all of
the different controls and policies that might be in play
in all of those cases and make
sure you test your apps configuration
across all of those potential scenarios
and we'll talk about some of the gotchas in a moment.
When a given issue comes up in
the area of consent and permissions,
the exact solution will vary quite
a bit depending on the specific situation.
It's important to take a step back and understand
what is going on before implementing a solution.
These generally are issues that should be
approached with a standard break fix mindset,
where you can just try a bunch of
different things until the issue
is resolved and then move on.
Even though the strategy might get rid of
the specific area you're seeing at the moment,
it could lead to much bigger issues down the line.
For this reason, the first thing to do when you encounter
an issue is to take a step back and frame the problem.
And this all starts with this scenario.
First and foremost, you want to think about what the goal
is of the app or the piece of
functionality that you're having problems with?
You want to ask questions like;
what data does it need to access and for what purpose?
You want to look at what error you're
seeing and where it's being thrown?
Is it coming from the authorized endpoint,
the token endpoint, the actual
API call or somewhere else?
Who is using an app?
Is this an end user or an admin?
If we're talking about Azure ID users here,
what consent and app access policies
might have been applied in that organization?
Next, it's important to think
about the application itself.
Is it using a client library?
If so, which one?
Is it targeting the V1 or the V2 endpoint?
What protocol flow is being used?
Is it using static dynamic or incremental consent?
If you don't know the answer
to these questions and didn't
build the app initially,
it'd be good to get
that information from the person who did.
It's going to save you a lot of headaches
and troubleshooting down the line.
Finally, it's good to
think about the resource that's being targeted.
What API or APIs are being called?
What permissions are being requested from these APIs?
Are they right for this scenario or are there others
possibly less privileged ones
that should be used instead?
To get more specific,
one of the more common issues we see in
this space is when a developer is getting a
403 unauthorized unexpectedly when
they actually expect all of their calls to succeed.
In this case, it's important to
understand what permissions have been requested,
consented to and who consented to those permissions.
It's also good to know whether these things actually
map to the specific call
the app is making which is failing.
It's also good to think about
the effective permissions in play here.
If the app is using delegated permissions,
the code could be failing because
the user who the app is acting on
behalf of doesn't have
permissions to take that action in the first place.
In some cases, there isn't much you can
do about that as a developer.
If a tenant admin has block
users from reading each other's profiles for example,
a 403 would be expected when
an app tries to take that action on
a user's behalf and apps will need to
respect that admins configuration for their tenant.
So, not all 403 should be considered unexpected or bad.
Another thing we see people struggle with,
is the case where a user isn't able to consent to an app.
This can happen if the app is requesting that
a non-admin user consents to admin restricted
permissions or if the users
admin has blocked end users
from consenting to apps altogether.
In either case, an admin will need to
consent in order for any end user to use the app.
One more issue we see on
occasion is the scenario where an admin
has consented to the app but
end users are still blocked from using it.
One common cause here is when
the developers is using the V2 endpoint and has
configured a very small number of
static permissions or just left the default one of
user.read selected in the portal but is asking for
a larger or completely different set of
permissions dynamically or in their code.
In this case, an admin does consent to
the app on behalf of all their users
in the organization successfully,
but they're consenting to a
different set of permissions than
the app is actually asking and users for it run-time.
This can be solved by ensuring that the list of
static permissions and application asks
for are always a super-set of
the permissions and app will be
requesting dynamically or incrementally.
However, this doesn't mean you should go and
request all available permissions statically,
stick with least privilege and only
ask for those you'll actually be using.
One last gotcha, is the scenario
where an admin requires that
users are assigned to
applications before they can sign in.
This requirement holds true even if consent has occurred.
So, as long as this is set,
the admin will need to go and assign each user that they
want to have access to
the app even after consent has occurred.
If you're having one of these issues and need to post on
stack overflow or open a support case to get help.
There are a few things can be helpful to include in
that request to expedite the process.
These include; the scenario when the goal,
the error code and the exception text you're seeing,
the time stamp and a correlation ID, your Tracking ID.
To wrap things up, always
abide by the principle of least privilege,
only ask for the permissions
your application absolutely needs when it needs them.
Also, be thoughtful when
requesting permissions and consent and when
configuring your application in
general and make sure to be scenario driven.
Consider all persona's and
possible customer configurations.
To learn more, check out
our documentation at: graph.microsoft.com Also,
make sure to check out our samples on
github and tell us
about what you're working on on Twitter.
If you have any questions,
make sure to post them on Stack Overflow using
the Microsoft Graph tag. Thanks for watching.