.NET Archives » Paul Ryan

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.

PowerShell recursion with delegate functions, iterate all lists in all webs

There are many ways to iterate a collection in PowerShell. I just really like using delegate functions. This approach is not native PowerShell but utilises the .NET Action class as a function parameter. Using a delegate function approach, it is possible to create a recursive loop that can be very easily reused in the future just by providing an alternative Action.

The example code I provide below demonstrates how to create a delegate function in PowerShell, how to write a function that accepts one as a parameter, and provides some ready made samples for iterating SharePoint objects, specifically all webs or all lists. I am using some specific SharePoint objects in these samples, however the fundamental pattern can be used to effectively iterate any recursive structure.

foreachDecendentWeb : perform an action on every web below the provided web
foreachListInWeb : perform an action on every list in the provided web
foreachListInWebAndAllDecendentWebs : perform an action on every list in the current and all decendent webs

Some notes

The below script references ‘TopOfScript.ps1’, it is specifically related to calling SharePoint CSOM from PowerShell. Read about it here on sharepointnutsandbolts.

Making the call, providing the delegate

# See Chris O'Brien's blog on using CSOM in PowerShell for # more information on 'TopOfScript'. In essence this just # defines the $clientContext object. # http://www.sharepointnutsandbolts.com/2013/12/Using-CSOM-in-PowerShell-scripts-with-Office365.html . .\TopOfScript.ps1 # Load root web $rootWeb = $clientContext.Site.RootWeb $clientContext.Load($rootWeb) $clientContext.ExecuteQuery() # Define the work that you want done here [Action[Microsoft.SharePoint.Client.List]]$printListName = { param([Parameter(Mandatory=$true)]$list) Write-Host "$($list.Title)" } # Kick it off! foreachListInWebAndAllDecendentWebs $rootWeb $printListName

The utility scipts, recursive functions accepting delegate parameters

function foreachDecendentWeb( [Parameter(Mandatory=$true)] [Microsoft.SharePoint.Client.Web]$web, [Parameter(Mandatory=$true)] [Action[Microsoft.SharePoint.Client.Web]]$webAction) { # Load child webs $context = $web.Context $childWebs = $web.Webs $context.Load($childWebs) $context.ExecuteQuery() # Iterate child webs foreach($childWeb in $childWebs) { # Perform action on child web $webAction.Invoke($childWeb) # Iterate child-child webs foreachDecendentWeb $childWeb $webAction } } function foreachListInWeb( [Parameter(Mandatory=$true)] [Microsoft.SharePoint.Client.Web]$web, [Parameter(Mandatory=$true)] [Action[Microsoft.SharePoint.Client.List]]$listAction) { # Load lists $context = $web.Context $lists = $web.Lists $context.Load($lists) $context.ExecuteQuery() # Iterate lists $listCount = 0 foreach($list in $lists) { # Perform action on child web $listAction.Invoke($list) $listCount++ } return $listCount } function foreachListInWebAndAllDecendentWebs( [Parameter(Mandatory=$true)] [Microsoft.SharePoint.Client.Web]$web, [Parameter(Mandatory=$true)] [Action[Microsoft.SharePoint.Client.List]]$action) { # Define per-list action [Action[Microsoft.SharePoint.Client.List]]$perListAction = { param([Parameter(Mandatory=$true)]$list) $action.Invoke($list) } # Define per-web action [Action[Microsoft.SharePoint.Client.Web]]$perWebAction = { param([Parameter(Mandatory=$true)]$web) foreachListInWeb $web $perListAction } # Perform action on root web $perWebAction.Invoke($rootWeb) # Perform action on every decendent web foreachDecendentWeb $rootWeb $perWebAction }

Paul.

ULS Log Analyser

Infrastructure contacted me to complain that one of our SharePoint environments was logging too much data (via the ULS) and it was becoming unmanageable (an Operations Management tool like SCOM has not been configured). Looking through many gigabytes of text, even with a free tool like ULSViewer, it is difficult to be confident that you are correctly identifying the most common issues, it is an inaccurate art at best.

That is why I wrote a log analyser as a PowerShell script which will process ULS log files and, using fuzzy comparison, create a report of the most frequently occurring log entries.

I am very well aware that this is not necessarily useful information in many cases (hence I had to write this script myself). Nevertheless I found it useful in my scenario and I hope that some of you may as well.

Just in case you are interested: using this script I was able to declare with certainty that logging by the SPMonitoredScope class made up almost 30% of total log entries. This will be reduced by explicitly stating the log severity in the class constructor as verbose and maintaining a log level of Medium for the SharePoint Foundation : Monitoring diagnostic logging category.

A few things of note:

You may want to add to or remove from the set of replace statements in order to increase/decrease the ‘fuzziness’ of the comparison. Adding a replace statement for removing URLs may be a good candidate if you wish to increase matches.
The script loads entire files into memory at once. Be aware of this if you have very large log files or not much RAM.
The output file is a CSV, open it with Excel.
By default the script will identify and analyse all *.log files in the current directory.
If you cancel the script during processing (ctrl+c) it will still write all processed data up until the point at which it was cancelled.

param ( [string]$inputFile = ".\*.log", # The log file to process [string]$outputFile = ".\LogAnalyser_$(Get-Date -Format yyyyMMdd-HHmmss).csv", [bool]$confirm = $true ) # support relative paths if(![string]::IsNullOrEmpty($inputFile) -and $inputFile.StartsWith(".")) { $currentPath = Split-Path -parent $MyInvocation.MyCommand.Definition $inputFile = $currentPath + $inputFile.TrimStart(".") } if(![string]::IsNullOrEmpty($outputFile) -and $outputFile.StartsWith(".")) { $currentPath = Split-Path -parent $MyInvocation.MyCommand.Definition $outputFile = $currentPath + $outputFile.TrimStart(".") } $rowsPerDotLoading = 10000 # for display purposes only $rowsPerDotWriting = 100 # for display purposes only $rowCount = 0 $distintRowCount = 0; $hash = @{} $prevLine = "" $files = (Get-ChildItem $inputFile) if($files -eq $null -or $files.Length -lt 1) { Write-Host "No input files found!" return } $fileTotalCount = $files.Length if($confirm) { Write-Host "Files: " $files | Foreach { Write-Host $_.Name } Write-Host ("Press 'y' to process $fileTotalCount file(s)") $key = $host.UI.RawUI.ReadKey("IncludeKeyDown") if($key.Character -ne "y") { Write-Host "" return } } $startTime = Get-Date $fileCount = 0 try { foreach($file in $files) { $fileCount++ Write-Host "" Write-Host "Reading $fileCount of $fileTotalCount, $($file.Name) ..." -NoNewline $fileContent = Get-Content $file Write-Host " done" Write-Host "Processing " -NoNewline foreach ($_ in $fileContent) { # split line $lineArray = $_.Split(([char]9)) #$timestamp = $lineArray[0] $process = $lineArray[1] -replace "$.+$", "" #$tif = $lineArray[2] $area = $lineArray[3] $category = $lineArray[4] #$eventId = $lineArray[5] $level = $lineArray[6] $message = $lineArray[7] #$correlationId = $lineArray[8] $hashKey = "$process,$area,$category,$level" if(!$hash.ContainsKey($hashKey)) { $hash[$hashKey] = @{} } $msgsHash = $hash[$hashKey] # handle multi-line log messages if($message.EndsWith("...")) { $prevLine = $prevLine + $message.TrimEnd('.') } else { if(![string]::IsNullOrEmpty($prevLine)) { $message = $prevLine + $message.TrimStart('.') $prevLine = "" } # perform fuzzing on the message $msgHashKey = $message $msgHashKey = $msgHashKey -replace "(\{{0,1}([0-9a-fA-F]){8}-([0-9a-fA-F]){4}-([0-9a-fA-F]){4}-([0-9a-fA-F]){4}-([0-9a-fA-F]){12}\}{0,1})", "GUID" # remove guids $msgHashKey = $msgHashKey -replace "$.+$", "(XXX)" # remove content of parentheses $msgHashKey = $msgHashKey -replace "\d*\.?\d+", "X" # remove numbers $msgHashKey = $msgHashKey -replace "\s+", " " # condense whitespace if(!$msgsHash.ContainsKey($msgHashKey)) { $msgsHash[$msgHashKey] = 0 $distintRowCount++ } $msgsHash[$msgHashKey]++ $rowCount++ if($rowCount%$rowsPerDotLoading -eq 0) { Write-Host "." -NoNewline } } } Write-Host " done" $fileContent = $null } Write-Host " done" -ForegroundColor Green } finally { Write-Host "" Write-Host "Writing $outputFile " -NoNewline Add-Content $outputfile "count,process,area,category,level,message" foreach($hashKey in $hash.Keys) { $msgHash = $hash[$hashKey] foreach($_ in $msgHash.Keys) { $count = $msgHash[$_] $message = '"' + ($_ -replace '"', '""') + '"' # csv escaping Add-Content $outputfile "$count,$hashKey,$message" if($distintRowCount%$rowsPerDotWriting -eq 0) { Write-Host "." -NoNewline } } } $hash = $null Write-Host " done" -ForegroundColor Green Write-Host "Distinct log rows: $distintRowCount of $rowCount" -ForegroundColor Black -BackgroundColor White $timeTaken = ((Get-Date) - $startTime) $timeSpanString = '{0:00}:{1:00}:{2:00}' -f ($timeTaken | % {$_.Hours, $_.Minutes, $_.Seconds}) Write-Host "Completed in $timeSpanString" -ForegroundColor Black -BackgroundColor White }

I quite enjoy PowerShell-ing so expect to see more utilities in the future.

The _layouts web.config for customErrors

There is a web.config file under the _layouts folder. This is worth being aware of as you may notice that files that you access from the _layouts folder may not behave as you would expect. This came to my attention when I was getting the following error:

”To enable the details of this specific error message to be viewable on remote machines, please create a tag within a “web.config” configuration file located in the root directory of the current web application. This tag should then have its “mode” attribute set to “Off”.

This initially surprised me as I knew that I had already done as such and had recently seen the default error screens when I was building web parts on content pages.

As the web.config under the layouts folder is deeper in the site hierarchy, any elements defined here will overwrite those defined at the web application level. By default the customErrors element exists at this level and it must be set accordingly to your needs as well.

As always, be careful when editing web.config files and always make a backup beforehand.