Tag: C#

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.

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.

Request Signing, Amazon Product Advertising API, .NET C#

The Amazon Product Advertising API documentation provides some code samples for its use but none using ASP.NET. A personal interest brought me to play with it and as it wasn’t entirely trivial to create a signed request as required associate authentication I thought I’d share some working code samples.

Amazon Product Advertising API

Some notes

The API does surface a WSDL file and as such a Web Reference could be used to generate classes to interact with the API. The sample I am providing here does not take advantage of this and is instead submitting raw REST requests.

I see the most valuable part of this sample as the request signing piece. This sample should not be seen as a best practice for interacting with the API but rather as a utility for request signing.

The order of the query string parameters that are included in the signed string is crucial. They must be ordered by character code (in practise this equates to alphabetically, but with all upper case letters coming before any lower case letters). The API documentation suggests string splitting, sorting, and string joining. This is definitely the approach I would take if you find yourself writing queries that use parameters dynamically but I struggle to see the use-case. This sample just uses a hard-coded string with the relevant parameters in the correct order.

Although I haven’t looked in detail yet, the approach taken to sign requests here appears very similar if not identical to that required by the Instagram API, and I am sure many other (social media) APIs.

Requests to APIs which require the signing of a secret key cannot be made securely directly from the client (e.g. using JavaScript) as it would require your secret key to be available in plain text on the client. If you want to run ajax commands against the API you need execute requests to an intermediary service. This is the approach that the sample code below facilitates.

You can read about the Amazon Product Advertising API here: Product Advertising API

The code

Below you will find a class called the AmazonApiHelper. Further below is an ashx HttpHandler as an example of calling the utility functions provided by the helper class. You’ll need to provide you own values for the following constants:
private const string awsSecretKey = "Your secret key goes here";
private const string awsAccessKeyId = "Your access key Id goes here";
private const string associateTag = "Your associate tag goes here";

The helper class

 

Calling the helper class from a web handler

Good luck advertising those products!

Paul.

Dynamically nesting CAML query statements

Here is a short PowerShell function that can be used when you need to dynamically generate CAML queries with many logically joined statements. I actually adapted it from a C# implementation I wrote (which is probably more useful…) but as you can rewrite it in C# very easily I won’t bother bother posting it twice.

As CAML logical join operators (And, Or) can only compare two statements, when many statements need to be compared you must nest them which is what this function achieves. The $join parameter should be passed as “And” or “Or” and the $fragments parameter should be passed as an array of CAML statement strings such as:
@("<Eq><FieldRef Name='Title' /><Value Type='Text'>title</Value></Eq>", "<Eq><FieldRef Name='FileLeafRef' /><Value Type='Text'>name.docx</Value></Eq>")

# Define method for nesting caml query statements
function GetNestedCaml([array]$fragments, [string]$join)
{
    if ($fragments.Length -lt 1)
    {
        return [string]::Empty
    }
    elseif ($fragments.length -eq 1)
    {
        return $fragments[0]
    }
    elseif ($fragments.length -eq 2)
    {
        return "<$join>" + $fragments[0] + $fragments[1] + "</$join>"
    }
    $joinFrags = @()
     $baseJoinCount = [int][Math]::Floor($fragments.length / 2)
    for ($i = 0; $i -lt $baseJoinCount; $i++)
    {
        $baseIndex = (2 * $i)
        $fragsToJoin = @($fragments[$baseIndex], $fragments[$baseIndex + 1])
        $joinFrag = GetNestedCaml $fragsToJoin $join
        $joinFrags += $joinFrag
    }
    if ($fragments.length % 2 -ne 0)
    {
        $joinFrags += $fragments[$fragments.length - 1]
    }
    return GetNestedCaml $joinFrags $join
}

List view sort order bug

SharePoint was once known for it’s unfortunate list of quirky bugs. As of SharePoint 2010 there are definitely less of these to contend with but some still remain – like this one. The sort order for a list view can get rendered incorrectly when editing the view.

When you define a view programmatically it is up to you to create the XML which defines it. A common view query for a tasks list may be to show all items in descending order so that the newest tasks appear at the top of the list. As such:



SPView view = list.Views["All Tasks"];
view.Query = "<OrderBy><FieldRef Name='ID' Ascending='False' /></OrderBy>";
view.Update();

This will update the view just as you or I would expect. However, there is a significant problem here. When a user modifies this view in the future (via the ViewEdit.aspx) the form will show the view is sorted on ID (correct) but the ‘Show items in ascending order’ radio button will be selected (incorrect). If the user now saves the form, perhaps having added another column, the incorrect sort order will be persisted. To avoid this issue you must capitalise the Ascending attribute value as such:



SPView view = list.Views["All Tasks"];
view.Query = "<OrderBy><FieldRef Name='ID' Ascending='FALSE' /></OrderBy>"
view.Update();

I’m unaware of anywhere within SharePoint that providing upper-case boolean attributes is bad practice so I would recommend always using FALSE instead of False and TRUE instead of True.

SPFileVersion: Handling SharePoint file versions programmatically

I recently had a requirement around linking to and downloading specific versions of documents stored in SharePoint. There is some rather quirky behaviour around SPFileVersion and how this is achieved and I felt it warranted a post.

Versions

The first thing to be aware of is that there are two distinct version collections: SPFileVersionCollection and SPListItemVersionCollection. These collections can be accessed via the respective assets as you would expect (SPFile.Versions and SPListItem.Versions) and, as is the way in SharePoint, are enumerations of SPFileVersion and SPListItemVersion objects, respectively. These objects, which represent the individual versions, have a number of similar properties and methods but do not share a base class nor an interface.

In order to access specific versions of documents, the approach I took was to store the VersionLabel (a property on both SPFileVersion and SPListItemVersion) and then retrieve the version by using this value in conjunction with GetVersionFromLabel (a method on both SPFileVersion and SPListItemVersion). This works but with a number of caveats:

  1. SPFileVersionCollection does NOT contain an entry for the latest version. This means that if the document has only a single version then this collection will be empty. If you want to access the latest version you must verify that the version label refers to the latest version by comparing it to the first entry in the SPListItemVersionCollection and if it is then access the SPFile directly. If you are accessing properties that are also present on an SPListItemVersion (ie not opening a stream) you can use that collection instead but you must also take note of the next point.
  2. SPListItemVersion.Url behaves unexpectedly in some situations. Assumedly this is to support directing underprivileged users away from minor versions that they are not allowed to see (although I don’t see how it achieves this), the Url for minor versions will be equal to that of the latest minor version when there is no published version. Always use SPFileVersion.Url.
  3. Minor versions get promoted when published, breaking links to the minor version. Example – You have a document currently at version 0.2, with a previous 0.1 version. When you publish this document you still only have two versions: 0.1 and 1.0. You will now fail to locate version 0.2. Don’t be fooled into thinking that using the VersionId property will solve this issue. It simply represents the the version label as an integer (+1 for each minor version, +512 for each major version). The only way I could find to handle this case is to introduce the doc store version which is stored in the property bag of the SPFile: SPFile.Properties["vti_docstoreversion"]. You can see how this works by looking at the code examples I have included but if this specific case isn’t going to be an issue for you then don’t use it and enjoy cleaner code (see here). Also note that the doc store version is only stored in the SPFile property bag and not in the SPListItem property bag.

I have included some code to illustrate how this may be implemented:

Please leave a comment and if you want to keep reading more about SharePoint don’t forget to subscribe.