[MUSIC]
Matthijs Hoekstra: Hello, my name is Matthijs Hoekstra.
I'm a Program Manager in the Azure Identity Engineering
organization. In this video, we're going to talk about
how you can implement authorization using application
roles and security groups.
So, let's start with application roles.
Application roles are actually used to assign a user to a
specific set of functionality in your applications.
They are defined in Azure Active Directory application
manifest, so they are specific to just a single application.
Removing the app in AAD will actually remove those roles
as well. If you use roles for your application assignments,
those roles will show up as a claim in your access tokens
and your ID tokens. You have to enable user assignment to
make it functional, so you can actually assign users to
those roles. So if you allow your app to use any user,
you don't force the administrator to assign roles to
those users when it's assigning users to your application.
So, best practice is to flip that switch to make sure that you
are requiring assigning users to your application as an
administrator. Roles are a bit more easy to use than groups
because you can hard code role names.
So in admin or regular user or an approver role, it's something
you can define in your application, hard code in your code.
Groups are typically more dynamic.
The group might not always have the same name.
If you would use group IDs, they might be different in every
single tenant, so roles are actually a better abstraction layer
to make sure some functionality is just available for those
folks with the right roles.
So, how does it work?
You have to define the role in the application manifest.
Then you assign roles to users and security groups.
And the assigned roles will be in the roles claim.
So, this is a screen dump of the application manifest.
We used this in a previous video to configure application
permissions as well; they are using roles as well but from the
type application.
Here, we're going to create an entry in the app roles array and
it's allowed member types from a type user.
These are user application roles. It has a display name.
For example, here, we have user readers and direct reviewers.
When you go to user assignment, after you assign the user,
you can actually select a role,
that’s the part on the right side.
So, what kind of role do you want the user to have?
And once that’s all in place and your application is asking
for an ID token or access token, roles will actually show up in
the tokens as a claim.
And you see that here as DirectoryViewers is a role in this
specific token.
So, let me show you how you actually do this.
First, let's go to my application blade.
I find my Cactus API.
We've used this API in previous videos.
So if you want more details, please view those videos to get
some more context.
So, we have a few permissions, but we also set up a few roles.
You either can be an administrator or you can just be a regular
user, and depending on those roles, we give you more access or
less access to the catalog.
I have to go to the manifest, and here you see the first user
application role.
It's called admin with some explanation what it is.
And I've got another one, which is called user.
So if I would go to my-I can just go from here to my
enterprise application, and I look at the users, I can actually
edit Megan and I can assign a role, so admin or user.
Because of those roles defined, I can actually assign Megan to
one of these two roles.
There's also a limitation currently with the UI.
I can only assign a user to a single role.
So if I have the scenario where I need to use multiple roles,
you should use groups and you should assign groups to those
different roles.
So, I could create an admin group for this app or a user group
for this app, put users in those right groups and I assign only
the user or the group to one of these roles.
This is literally it.
So, your application can now receive tokens where depending on
what people are assigned to, there's a role claim in the token.
And you as a developer can use that claim, that piece of
string, to figure out what that means for your
authorization scheme.
So if you want to use this in your application,
and here's an example, you can actually use this in your
ASP.NET application. You have to set up the
middleware correctly.
Say, well, I want to accept these role claims and what you can
do then in your controls instead of just using authorize,
you can actually ask, well, I've authorized this controller
but only for the roles that are DirectoryViewers, Subscriber,
Writer, or Approver.
Or you can use a piece of code where you do User.IsInRole.
This is no different than any other authorization scheme you
have been using in the past.
So when you're using Azure Active Directory, you hooked up
ASP.NET correctly with AAD, those roles will show up as a
claim, and you can just do coding like you did before.
So, this is not specific to Azure Active Directory,
this is just something you have been doing for years.
So, how do you configure it?
Well, you have to set up Azure AD and I've showed it in other
videos as well, but this is what it is.
You have some configuration like a client ID and all that
stuff. That's what you create when you create the first
application registration. And you actually say, well,
I want TokenValidationParameters to
include RoleClaimType, so that means that the roles will
actually transfer to the claims principle, and that's what
ASP.NET actually uses when they do the authorization.
So, this is just metadata on top of your controllers,
no coding involved. And ASP.NET will actually handle this
for you or will give you an access denied if you don't
have the right roles and you're trying to
access this controller.
So, how about security groups?
Sometimes we see our customers actually want to use security
groups in their code as well, and there's a few different ways
you can do it.
We talked about Microsoft Graph in other videos, where you can
actually do a call to the Graph and figure out if you place
member of certain groups, but we can actually make this a
bit more optimized for you as well.
So, what are security groups?
It's a collection of users assigned to this group and you can
actually assign rights to that security group.
They can be cloud only; that means they only exist in Azure
Active Directory, but they can come from your on-prem Active
Directory as well and maybe are sync'd to Azure Active
Directory. Groups are typically not tied to an application.
They are available or generally available to anybody in the
organization, so they can be used in multiple apps.
This is actually a good thing.
Sometimes you have a suite of apps and you want to grant access
to just those apps for a set of users.
Instead of using the user configuration in all those different
apps, an administrator might decide to use a group and use that
group for all those apps.
And just by using group management and add a user to that
group, they automatically get access to all those applications.
At this moment, we don't support nested groups in Azure Active
Directory yet, so that's something you have to be aware of.
So, how does it work?
Again, users can be assigned to security groups by an admin.
Developers can code groups' permissions in their apps.
And to get those group IDs easily, we can actually pass along
those group IDs as a claim in your tokens.
You have to do this by changing the app manifest.
And once you do that, the group IDs will be part of your token.
So, this is the change in the manifest.
You go to groupMembershipClaims and you specify I want to
have the security group. You can have none.
You can also have all.
This will mean that you can not only have the security groups,
you also get the distribution groups and Azure AD directory
roles. And this is what shows up in your token.
So, you have groups with a bunch of group IDs.
And again, I talked about where the abstraction might sometimes
be easier to do with roles.
The group IDs are typically unique for your tenant only,
and you have to hard code those group IDs inside of your
application or if the administrator is some of UI where it can
specify, you know, I only care about these group IDs and for some
I want to tie certain action when people are actually part of
this group ID or not. So, it might be a bit more work.
You can also change the tokens to add more optional claims,
for example, sam_account_name or the
dns_domain_and_sam_account_ name and emit_as_role.
By default, we only have the ObjectIDs as a group as a claim,
and you can change this to change.
So, these are the valid options:
dns_domain_and_sam_account_name,
netbios_domain_and_sam_account_name, emit_as_roles.
This only works for groups which are sync'd from on-prem these
options. That's something you have to be aware of.
So, we get a lot of questions about, well, I want the group
name, I don't care about the group IDs.
That only works for groups which are being sync'd from an
on-prem Active Directory.
So, if I get this information in a claim, then you can see,
look, I've got groups and one of the group names is MS Demo
Users. And we don't do a mix of AAD groups and on-prem
groups, so it is either one or the other.
So, we don't mix up on-prem user group names and mixed with
group IDs from AAD, so you have to be aware of that.
So, we only return the group names of on-prem groups
at this time.
You can also set up the option where we return the group names
as roles.
So, that might be useful if you want to do IsInRole MS Demo
Users, and do the role claim, so your code is simple.
That's the change you have to do with the samAccountName or the
emit as roles option we talked about before.
So, how does it look like?
Back to my simple WPF app and the source code will be linked in
the description below.
If I sign in as a user and I show you the ID token and the
claims, let me sign in as Megan first.
Megan isn't part of too many groups, hopefully.
See, I logged in and I will show you a list of group IDs.
So, this might be useful for your scenario.
What happens if I'm a member of too many groups?
I've been working with Microsoft for some time, so over the
time you start collecting group memberships, I guess.
So, every year you're at the company, they add you to more and
more groups. So, we don't want to send too big of tokens,
so we call this a group overage claim.
If there's too many groups for us to put in a token,
we will change the claims in the token.
This typically has to do with the HTTP header size limits.
We cannot send too big of tokens over the wire as an HTTP
header. So, it depends a bit on what kind of application
you are building, if it's a JavaScript app or an ASP.NET app,
where we limited the amount of claims so to say.
So if you build a SAML app, which is a different protocol,
we only share 150 group IDs. For OIDC or OAuth,
JWT tokens, it can be 200.
And if it's more than that, instead of group IDs, we emit an
overage claim.
And this is how it looks like.
So, well, there's a claim names groups called source 1.
And that source 1 actually shows you an endpoint, which is a
Graph API call you can do, and figure out what all the
memberships are. So, this is actually us telling you
through a token and claims, like there's too much groups
for this user to put in his token.
You as a developer have to figure this out yourself.
So, assume when you use this that there might be too many
groups. You always have to have this backup code to call
this API to figure out what the rest of the groups are.
Again, the limitations for JWT tokens, there's only six for
implicit flow applications.
And the reason being that it is a single page app,
it goes to redirects and the URIs can just be so long.
If there's too many groups, the claim will be returned like has
groups and you still have to do the work to figure out what
groups people are a member of.
So, again, we check for the claims name and for one of the
values of those groups, this indicates overage.
If found, you have to call this endpoint to find out all the
group membership of this user.
You have to get an access token for the Microsoft Graph with
the User.Read and the Group.Read.All permission.
This is a permission only an admin can consent to.
So, that might be a barrier for you to implement this
functionality, but this is what you need.
If you didn't find this claim, you can look for the groups
claim and find the group's IDs.
So, caveats for this functionality, we don't support nested
groups, a group's capability varies between Azure AD editions,
Azure AD roles are sent in the wids claim.
This is the configuration you do for group IDs.
So, again, you configure the Azure Active Directory and you can
do, I want a role claim type as groups.
What happens if the groups are returned, the ASP.NET middleware
actually puts those groups as a role claim, so you can actually
do roles is group objectId and hard code authorization here.
And, again, this is the thing, group object IDs are typically
different for a tenant, so if you build a multi-tenant
application, make sure there's some way for an administrator to
specify this. But the thing is if you hard code it,
you don't have the flexibility to change those group IDs,
so this might just work for your own organization.
You can also use the samAccountNames, which is a more readable
format but again only 40 on-prem groups.
There are some licensing caveats as well.
So, we've got different license models for Azure Active
Directory. A regular license is free, but we have a P1 and a P2
license as well.
If you want to assign roles to users,
that's available in the free edition.
If you want to sign security groups to roles,
that's a premium edition you can use.
So, that actually concludes this video talking about how you
can use group and group IDs, group names and roles to specify
more authorization possibilities for your application.
I hope you enjoyed the video and I'll see you next time.
[MUSIC]