If you’re a developer of a SaaS application that allows business users to create and share content – it is likely that your customers have requested the ability to grant access to Active Directory groups. For traditional applications running within the enterprise boundary (and having access to Active Directory over LDAP), it is straight forward to provide AD groups based sharing/access management. Azure Active Directory makes it simple for applications deployed in the cloud also to enable access management using AD groups.
With just a few clickAzure AD customers connect and synchronize their on-premises Active Directory to the cloud. Small size customers of Microsoft services (like Office 365, Azure) that do not have on-premises AD get an Azure Active Directory in the cloud in which their identities are mastered. By integrating authorization with Azure AD groups, cloud applications enable customers to not only leverage on-premises AD groups for access management but also groups from other sources like Exchange Online, Workday etc.
The work involved to enable groups based access management can be conceptually divided into two pieces:
- Access Management: The application needs to allow users to search and pick groups when they are managing access to their content. The experience here could be as simple as a text box that receives the search string (e.g. “ellen”) and searches Azure AD for users and groups that match that string and allow the user to pick the one they want to grant access to.
- Access Check: When the application shows to a user, the resources they have access to or authorizes when the user tries to access a resource, the application needs to consider the user’s group membership also when performing access check (because the resource might be shared not directly with the use but instead with a group that the user is member of). For this we have recently turned on a new feature called group claim in Azure AD. When the groups claim is enabled for an application, Azure AD includes a claim in the JWT and SAML tokens that contains the object identifiers (objectId) of all the groups to which the user belongs, including transitive group membership. To ensure that the token size doesn’t exceed HTTP header size limits, Azure AD limits the number of objectIds that it includes in the groups claim. If a user is member of more groups than the overage limit (150 for SAML tokens, 200 for JWT tokens), then Azure AD does not emit the groups claim in the token. Instead, it includes an overage claim in the token that indicates to the application to query the Graph API to retrieve the user’s group membership. Conceptually, this is similar to Windows Server Active Directory’s capability of including token group membership information in Kerberos tickets.
Alright, it’s time we get into the details. By the way, the code that I refer to is from the sample application published at: https://github.com/dushyantgill/VipSwapper. The application MVC sample application is running in Azure websites here: http://www.VipSwapper.com/TrainingPoint. We will begin by enabling the groups claim for the application and then we will add code to the application to enable access management using groups.
Enable groups claim for your application
Either the application owner (developer of the app) or the global administrator of the developer’s directory can enable groups claim for an application: in the Azure management portal, navigate to the Active Directory node and go to the Applications tab. Click to open the application for which you wish to enable groups claim. Click on the Manage Manifest action button on the bottom bar and select to Download Manifest. Open the manifest file in a JSON editor of your choice.
Locate the “groupMembershipClaims” setting. Set its value to either “SecurityGroup” or “All”.
| “SecurityGroup” | groups claim will contain the identifiers of all security groups of which the user is a member. |
| “All” | groups claim will contain the identifiers of all security groups and all distribution lists of which the user is a member. |
Save the updated application manifest JSON file and upload it using the Manage Manifest action button, for the setting to take effect.
Next, you must enable your application to query Azure AD Graph API on behalf-of the user. In the case of groups overage, when group membership data does not arrive in the token, your application will query Graph API to get the user’s transitive group membership. Go to the configure tab of the application and scroll down to the ‘permission to other applications’ section. In the delegated permissions dropdown for the Azure Active Directory row, select the ‘Read directory data’ permission.
Process groups claim
Authentication flows that support groups claim
Once groups claim is enabled for an application, Azure AD issues the groups claim for the following authentication flows. To ensure that the token containing groups claim doesn’t exceed the query string size limits of browsers, Azure AD emits the groups claim only in the authentication flows in which the token travels over POST.
|
Auth flow supported by Azure AD |
Groups claim issued? |
| SAML/WSFed SSO. Response over POST binding | Yes – in the SAML token |
| OpenIDConnect SSO (id token). Response over POST | Yes – in the id token |
| OpenIDConnect SSO (id token). Response over Query String or Fragment | No |
| OAuth Authorization Code Grant, Resource Owner Password Credential Grant, Refresh Token Grant, Access Token Grant and Extension Grants | Yes – in the access token |
| OAuth Implicit Grant Flow | No |
| OAuth Client Credential Flow | Coming in a future release |
Groups claim type and value
The claim type of the groups claim in the JWT tokens is ‘groups’. The value is an array of group objectIds represented as strings.
The Attribute Name of groups attribute in the SAML tokens is ‘http://schemas.microsoft.com/ws/2008/06/identity/claims/groups’. It is a multi-valued attribute.
Groups claim overage
If the user is a member of more groups than the overage limit set by Azure AD (150 for SAML tokens, 200 for JWT tokens), Azure AD issues an overage claim in the token. Upon receiving this claim the application must query the Azure AD Graph API to retrieve the all the groups to which the users belongs.
Groups overage condition is indicated in the JWT tokens via claims of type: ‘_claim_name’ and ‘_claim_sources’.
Groups overage condition is indicated in the SAML tokens via claim of type: ‘http://schemas.microsoft.com/claims/groups.link’
The following code in GraphUtil.cs of the sample application gets the user’s group membership. It detects the groups claim overage condition and queries Azure AD Graph API. NOTE that if users groups aren’t present in the token due to overage, production application shouldn’t query Azure AD Graph API at every access check (as the sample application), but instead cache the user’s group membership for that session.
public static async Task<List<string>> GetMemberGroups(ClaimsIdentity claimsIdentity)
{ //check for groups overage claim. If present query graph API for group membership
if (claimsIdentity.FindFirst("_claim_names") != null
&& (Json.Decode(claimsIdentity.FindFirst("_claim_names").Value)).groups != null)
return await GetGroupsFromGraphAPI(claimsIdentity);
return claimsIdentity.FindAll("groups").Select(c => c.Value).ToList();
} |
The following code in the GetGroupsFromGraphAPI method in the GraphUtil.cs file in the sample applicationextracts the getMemberObjects Graph API method URL from the groups overage claim.
</pre>// Get the GraphAPI Group Endpoint for the specific user from the _claim_sources claim in tokenstring groupsClaimSourceIndex = (Json.Decode(claimsIdentity.FindFirst("_claim_names").Value)).groups;
var groupClaimsSource = (Json.Decode(claimsIdentity.FindFirst("_claim_sources").Value))[groupsClaimSourceIndex];
<pre> |
Query Graph API for transitive group membership of the user
The getMemberObjects method in Azure AD Graph API returns the objectIds of all the groups that the user is a member of. By setting the ‘securityEnabledOnly’ parameter to true, the API can be made to return on the security group membership of the user. If ‘securityEnabledOnly’ parameter is set to false, then the API returns objectIds of security groups as well as distribution lists to which the user belongs.
https://graph.windows.net/{directory_name_or_id}/users/{user_objectid_or_upn}/getMemberObjects
Your application does not need to construct the entire query URL, it is sent as part of the overage claim value. You must append to it the api-version query string parameter with the Azure AD Graph API version that your application uses and query the URL. The following code in the GetGroupsFromGraphAPI method in the GraphUtil.cs file in the sample application does that:
string requestUrl = groupClaimsSource.endpoint + "?api-version=" + ConfigurationManager.AppSettings["ida:GraphAPIVersion"];
// Prepare and Make the POST requestHttpClient client = new HttpClient();
HttpRequestMessage request = new HttpRequestMessage(HttpMethod.Post, requestUrl);
request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", result.AccessToken);
StringContent content = new StringContent("{\"securityEnabledOnly\": \"false\"}");
content.Headers.ContentType = new MediaTypeHeaderValue("application/json");
request.Content = content;HttpResponseMessage response = await client.SendAsync(request); |
Access management experience using Azure AD groups
Finally, your application must allow users to search for the AAD groups to which they wish to grant access. For this you will use the Azure AD Graph APIs for searching and/or enumerating users and groups. In the access policy that your application stores, make sure to identify the AAD groups (to which access has been granted) by their objectId.
The following method in the GraphUtil.cs file in the sample application resolves the objectId of the Azure AD user or group given a search string.
public static string LookupObjectIdOfAADUserOrGroup(string searchString)
|
The following method in the GraphUtil.cs file in the sample application resolves the display name of an Azure AD object given their objectId.
string.
public static string LookupDisplayNameOfAADObject(Guid objectId)
|