Active Directory Archives

OAuth On-Behalf-Of Flow: Getting a user access token without user interaction. Includes ADAL sample.

OAuth 2.0 (and hence Azure Active Directory) provides the On-Behalf-Of flow to support obtaining a user access token for a resource with only a user access token for a different resource – and without user interaction.
This supports the scenario where a secured Web API acts as an interface to other resources (a.k.a endpoints) secured by the same identity provider and that require user context. As a practical example, a mobile client accesses some resources via a middle tier API which provides services such as data processing, caching, API simplification/optimisation, joining of datasets, etc.

The OAuth flow that achieves this is called the On-Behalf-Of flow; this makes sense as we’re facilitating the middle tier to act on behalf of the client when it accesses the resources farther down.

Using the on-behalf-of flow to access a resource via a middle tier API

Some background

Authentication with an OAuth 2.0 identity provider (such as AAD) produces JWT tokens. These tokens include information such as which claims (permissions) the user should be granted and the particular resource at which the token is valid (such as graph.microsoft.com). The OAuth 2.0 framework is specified such that a given token can only ever be valid for a single resource. This means that the token received by an endpoint (such as an Azure App Service Web API) cannot be used to directly authenticate to ‘another resource’. This is because the token’s resource will be that of the Web API and not the ‘other resource’. To see this I recommend checking out jwt.io and cracking open some tokens.

For completeness, the ‘other resource’ could be accessed using app-only authentication if it supports it, and if user context is not required (i.e. the return value will be the same regardless of the user) although this may greatly increase complexity in a multi-tenant scenario.

Configuring AAD for on-behalf-of

Before we get to the code the first hurdle is configuring AAD app registrations correctly. Initially it may be tempting to consider having both the Client and Web API layers utilise a single AAD app registration. After all, they are same holistic ‘app’ and how else can we get a user to consent to the permissions required by the Web API app when there is no interactive interface at that point? The latter point is resolved by explicitly binding the app registrations so that both are consented to as one. I mention how this is done below. By having two app registrations the flexibility of configuration is improved; we can have a Native app registration for the client and a Web API app registration for the Web API, we can have implicit flow configured for one app and not the other, and generally have granular control over configuration. Most vitally, an app registration can’t issue tokens valid for its own resource so two app registrations is a requirement.

I’ll avoid stepping though the configuration of the app registrations here as this is available elsewhere including this GitHub project. I will give a high level overview of what needs to happen.

1. Create app registration for the Web API
  - Assign permissions to the downstream resources (e.g. Microsoft Graph, a custom Web API, etc)
  - If supporting multi-tenant authentication ensure availableToOtherTenants is set to true in the manifest
2. Create app registration for the Client
  - Assign permissions to the app registration created above for the Web API
  - If supporting multi-tenant authentication ensure availableToOtherTenants is set to true in the manifest
3. Associate app registrations
  - In the manifest for Web API app registration, configure knownClientApplications to reference the App ID for the app registration created for the Client. E.g. "knownClientApplications": ["9XXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXc"]
    This binds the app registrations such that the Web API app registration is consented to as part of a single consent dialog displayed to a user when they authenticate to the Client app registration.

Before and after the app registrations are associated. Note how ‘Access Mobile App Backend’ is no longer present and instead is expanded to show the individual permissions required by that app.

Access Token Broker code

The following code is a .NET example of how to use the Active Directory Authentication Library (ADAL) to achieve the On-Behalf-Of flow.

using Microsoft.IdentityModel.Clients.ActiveDirectory; using System.Security.Claims; using System.Threading.Tasks; namespace PR.Azure.Core.AccessTokenBrokers { public class AdalAccessTokenBroker //: IAccessTokenBroker { public async Task<string> GetAccessTokenOnBehalfOfAsync( string accessToken, string appId, string appKey, string resource) { ClientCredential clientCred = new ClientCredential(appId, appKey); string tenantClaim = "http://schemas.microsoft.com/identity/claims/tenantid"; string authority = string.Format("https://login.microsoftonline.com/{0}", ClaimsPrincipal.Current.FindFirst(tenantClaim)?.Value); // NOTE : Implement a Redis token cache or token will be fetched from AAD every time. // E.G. https://blogs.msdn.microsoft.com/mrochon/2016/09/19/using-redis-as-adal-token-cache/ //TokenCache tokenCache = new RedisTokenCache(ClaimsPrincipal.Current.FindFirst(ClaimTypes.NameIdentifier)?.Value); //AuthenticationContext authContext = new AuthenticationContext(authority, tokenCache); AuthenticationContext authContext = new AuthenticationContext(authority); UserAssertion userAssertion = new UserAssertion( accessToken, "urn:ietf:params:oauth:grant-type:jwt-bearer", ClaimsPrincipal.Current.FindFirst(ClaimTypes.Upn)?.Value); // NOTE : May want to handle retry in case of transient errors AuthenticationResult result = await authContext.AcquireTokenAsync(resource, clientCred, userAssertion); return result?.AccessToken; } } }

Credits and further reading

This GitHub project was a very useful resource and a recommended starting point:
https://github.com/Azure-Samples/active-directory-dotnet-webapi-onbehalfof-ca

Microsoft docs OAuth 2.0 On-Behalf-Of flow
https://docs.microsoft.com/en-us/azure/active-directory/develop/active-directory-v2-protocols-oauth-on-behalf-of

OAuth 2.0 specification
https://tools.ietf.org/html/rfc6749

Redis Token Cache example
https://blogs.msdn.microsoft.com/mrochon/2016/09/19/using-redis-as-adal-token-cache/

Vardhaman Deshpande – always helpful
http://www.vrdmn.com/

I was inspired to write this post not because this information isn’t available but because the information is hard to find if you aren’t familiar with the term “On-Behalf-Of”. Hopefully this post will be found by those of you searching for terms like “trade access token for new resource”, “change token resource”, “use access token with multiple resources/endpoints”, “access Microsoft Graph via Web API”, etc.

Paul.

User photos in Office 365

The user photo story in Office 365 is not so straight forward. Photos are stored in Active Directory (AD) on-premises, Azure Active Directory (AAD), Exchange Online (EXO), SharePoint Online (SPO), and at first appearances possibly elsewhere as well (where does my Delve profile picture live, what about my Skype for Business (SfB) avatar?).

I have put together a flow diagram to represent how this actually works. It aims to demonstrate where user photos are stored and where different applications fetch user photos from (if they don’t store the images), and leads to some recommendations about user photo synchronisation.

Please note the date of this article (August 2016) and be conscious that Office 365 is changing rapidly and the following recommendations may have changed (e.g. Prior to the Delve user profile page, the SharePoint user profile page referenced images stored in SharePoint rather than Exchange. Changes such as these will continue to evolve).

User photos: the diagram

Where applications store and fetch user photos

Photo Location	Comments	Size	Is source?
On-premises AD DS in the thumbnailPhoto attribute	100Kb maximum	Recommended to be 96×96 or 48×48	Yes
Azure AD in the thumbnailPhoto attribute	100Kb maximum Usually synced from AD DS via Azure AD Connect	Recommended to be 96×96 or 48×48	No. Sync from AD
Exchange Online as property of the mailbox	500Kb Provided manually by users or a bulk import can be scripted if source photos can be located and named appropriately. If not provided, Exchange will reference the AAD thumbnailPhoto in some instances but only if the thumbnailPhoto is less than 10Kb. Does not sync back to AD	Recommended to be 648×648	Yes
SharePoint Online ‘User Photos’ library	Three renditions of the EXO photo are automatically created in SharePoint after upload to EXO. It generally takes up to 72 hours to see changes to EXO photo here. Sometimes we see that a user must ‘touch’ their profile before the sync will be performed. NOTE: Updating user profile photo via Delve profile is actually updating EXO profile photo and not performing any actions directly in SharePoint Online.	Small is 48 x 48, Medium is 72 x 72, Large changes depending on the source image but is always square. I have seen as small as 120 x 120 and as large as 300 x 300. PnP image upload solution uploads these as 200 x 200.	No. Sync from EXO
Skype for Business	Does not store any images Uses the high resolution Exchange image if available, otherwise uses the AD thumbnailPhoto	EXO image or AD thumbnailPhoto	No. Read from EXO
Delve user profile	Does not store any images Uses the high resolution Exchange image if available, otherwise uses the AD thumbnailPhoto	EXO image or AD thumbnailPhoto	No. Read from EXO
Yammer	Also stores its own photo. Out of scope of this discussion for now.		Yes

Likely issues and resolutions

Issue

Resolution

Exchange Online user photo is low quality (and in turn so is the SPO photo and SfB photo)

The source image coming from AD was/is low quality.

EXO user photos can be updated by users individually or if high res source photos are available this import can be scripted.

Source images should be jpg of 648×648 (resizing and compression can also be scripted)

Exchange Online user photo is high quality but SfB photo is low quality

High resolution photos from Exchange will be used as long as both Exchange and Sfb/Lync are of new enough versions (2013 or greater) and SfB is configured to allow all photos (not just those from AD).

NB. If a user doesn’t have a mailbox (e.g. not licenced) then they will be displayed using the AD photo

There is no Exchange Online user photo (and in turn there is no SPO photo or SfB photo)

A photo has not been imported to the user’s EXO mailbox and the AAD thumbnailPhoto either doesn’t not contain an image or that image is greater than 10Kb.

Import of photos up to 500Kb to EXO mailbox can be scripted (the source images could be on a file share, or AAD).

Changes to user photos are reflected quickly in Exchange and Skype but take days to replicate to SPO

Exchange to SPO synchronisation is a periodic process and can take up to 72 hours.

A custom solution can perform this replication on demand (e.g. at the same time EXO user photos are set)

User photos changed in other systems which update AD are not reflected in EXO, SPO, SfB.

E.g. A user in an on-premises SharePoint farm updates their user photo

When AD is updated, it is synchronised with AAD but that is as far as it gets as the “sync” from AAD to EXO is one-off import rather than a Sync.

Unlikely to be desirable to create a custom sync relationship here as users will want to be able to update EXO directly and won’t want their photo’s overwritten

User photos updated in EXO aren’t replicated to other systems which share an AD.

E.g. An on-premises SharePoint farm

The user photo in EXO is not synched back to AD – it can’t be consistently as the AD thumbnailPhoto attribute only supports photos up to 100Kb where EXO supports larger images.

Potential for a custom solution to sync images back to AD after having resized/compressed them to <100kb – However general recommendation is that AD thumbnailPhoto optimal size is 10Kb and 96×96.

Recommendations

Use Exchange user photos as the master. Allow users to update their user photos but pre-populate their user photo if possible and before end users are provided any access to the system.

If high resolution photos are available, script import of high resolution photos (648×648) to Exchange Online (see Set-UserPhoto and this and sample script below). These will then be visible in Exchange, in Skype, and, once processed, in SharePoint Online. In a dispersed environment this may have to be managed by many teams rather than trying to compile a single list of all user photos.

Users may then update their user profile photo directly via Outlook or indirectly via their Delve profile.

If synchronisation back to AD is required in order serve other applications (e.g. an on-premises SharePoint farm) then a custom solution could provide synchronisation from EXO to AD but this process should compress and shrink images as the recommended size of thumbnailPhoto images is only 96×96 and 10Kb.

Sample usage of the Set-UserPhoto cmdlet

# UPDATE THESE VARIABLES $userDomain = "@tenant.onmicrosoft.com" $photoFolderURL = "C:\Users\paul.ryan1\Desktop\people\" $data = @( @{ User = "alex.law" + $userDomain; PictureURL = "cast-aaron-j-albano.jpg"; }, @{ User = "david.bowman" + $userDomain; PictureURL = "cast-richard-todd-adams.jpg"; }, @{ User = "matthew.holden" + $userDomain; PictureURL = "cast-quentin-earl-darrington.jpg"; }, @{ User = "alex.dorrian" + $userDomain; PictureURL = "cast-christopher-gurr.jpg"; }, @{ User = "catherine.conroy" + $userDomain; PictureURL = "cast-emily-tate.jpg"; }, @{ User = "sandy.truong" + $userDomain; PictureURL = "cast-samantha-sturm.jpg"; }, @{ User = "claire.rowe" + $userDomain; PictureURL = "cast-lili-elizabeth-froehlich.jpg"; }, @{ User = "christian.ramirez" + $userDomain; PictureURL = "cast-zachary-downer.jpg"; }, @{ User = "paul.ryan" + $userDomain; PictureURL = "cast-tyler-hanes.jpg"; }, @{ User = "tim.wallis" + $userDomain; PictureURL = "cast-colin-cunliffe.jpg"; }, @{ User = "chris.obrien" + $userDomain; PictureURL = "cast-andy-huntington-jones.jpg"; }, @{ User = "sarah.johnson" + $userDomain; PictureURL = "cast-claire-rathbun.jpg"; }, @{ User = "ben.athawes" + $userDomain; PictureURL = "cast-marc-heitzman.jpg"; } ) # SCRIPT STARTS HERE $MSOLCred = Get-Credential $ExSession = New-PSSession -ConfigurationName Microsoft.Exchange -ConnectionUri https://outlook.office365.com/powershell-liveid/?proxymethod=rps -Credential $MSOLCred -Authentication Basic -AllowRedirection $Import = Import-PSSession $ExSession -CommandName Set-UserPhoto -AllowClobber Write-Host "Uploading user photos:" $count = 0 try { $data | ForEach { Write-Host "$($_.User)..." -nonewline try { Set-UserPhoto -Identity $_.User -PictureData ([System.IO.File]::ReadAllBytes($photoFolderURL + $_.PictureURL)) -Confirm:$false Write-Host " done" -f green $count++ } catch [System.Exception] { Write-Host " failed!" -f red } } } finally { Remove-PSSession $ExSession } Write-Host "Successfully uploaded $count photos"

Paul.

Azure AD app wildcard Reply URL

Azure AD apps (a.k.a Azure Active Directory apps, a.k.a AAD apps) are an essential component when interacting with Office 365 data outside of SharePoint – Mail, Calendar, Groups, etc.

As an O365 developer I have found myself writing JavaScript code against AAD apps (using ADAl.js) and often, especially during development, found myself entering a long list of Reply URLs. Reply URLs must be specified for any location from which authentication to AAD occurs. From a practical standpoint this results in someone (an Azure Administrator) having to update the list of Reply URLs every time a web part is inserted into a page or a new site is provisioned which relies on an Azure AD app.

If this is not done, the user is redirected to Azure login failure with ‘The reply address … does not match the reply addresses configured for the application’.

Error when Reply URL is not correctly specified

Perhaps the following is documented elsewhere but I have not come across it – a Reply URL can be specified using wildcards!

Probably the most common use for this is to end a Reply URL with an asterisk (wildcard) which will permit any URL which begins with the characters preceding it.

e.g. https://tenant.sharepoint.com/*
This example would support any URL coming from any page in SharePoint Online from within the named tenant.

It is also possible to use the wildcard character elsewhere in the Reply URL string.
e.g. https://*.sharepoint.com/*
This example would support any URL coming from any page in SharePoint Online from within *any* tenant.

Armed with this knowledge, be responsible and limit strictly how it is utilised. The implementation of Reply URL is a security feature and it is important that only trusted locations are allowed to interact with your app. I recommend only using wildcard Reply URLs in development environments.

Paul.