How to Handle Credential Provisioning and Key Rolling with the Microsoft Graph API

Not too long ago I investigated the options to manage the lifecycle of Azure Active Directory app registrations at scale. Most importantly, it needed to be fully automated; the numbers are simply too large to have manual steps in the entire process. For obvious reasons, the Microsoft Graph API plays a big role in making this a reality. And while the documentation and samples are pretty comprehensive (especially for the more common use cases), I stumbled upon a little gem in the API that’s not documented at all, and only sparsely so in the documentation for the Azure AD Graph API (the predecessor of the Microsoft Graph). It’s the addKey (and removeKey) action on the Application object, and in the end it enabled me to do key rolling with nothing more than direct communication between the registered app and the Graph API. But it took me half a day to get it to work, so I’m sharing my findings here; maybe it saves someone that half a day. I’ll be going through the details of how this works; if you’re just looking for the end-to-end solution, just skip right over there.

Let’s start with an outline of what we’re trying to achieve. First of all, upon provisioning a new app, we want to provision it with a temporary key of some sort. This temp key should enable the app to generate and register its own key that has a more extended validity period. That way, we want to ensure that only the app itself and Azure AD have knowledge of keys that are valid for a prolonged period of time. And secondly, even though the app-generated key should be valid for a longer period, best practices dictate that it should still have an expiration date. Determining a reasonable validity period depends on the context and possible compliancy regulations, but something like 1 or 2 years would be typical. When the expiration date approaches, the app needs to generate a new key, register that with Azure AD, and possibly retract the previous key.

Now, Azure AD app registrations allow for both symmetric and asymmetric (i.e. certificate) keys, but it’s a best practice to use asymmetric keys wherever possible. To add to that, certificate credentials are required for the approach I’m detailing here, so we’re using certificates. All the heavy lifting is done by a request to https://graph.microsoft.com/v1.0/applications/{id}/microsoft.graph.addKey
– which, as said, is not documented anywhere in the documentation. It is mentioned in the Azure AD Graph API documentation, and it was only through the Microsoft.Graph Nuget package that I suspected it might be available and functional in the Microsoft Graph. So based on the Azure AD Graph docs, let’s dissect all the pieces for a valid request.

Authorization header

Of course, every call to the Graph API must include a Bearer token in the Authorization header. There are numerous examples online on how to obtain such a token; one way would be to use the Microsoft Authentication Library (MSAL):

private async Task<string> GetTokenAsync(string appId, X509Certificate2 certificate, string tenantId)
{
var app = ConfidentialClientApplicationBuilder.Create(appId)
.WithAuthority($"https://login.microsoftonline.com/{tenantId}/")
.WithCertificate(certificate)
.Build();
var scopes = new[] { "https://graph.microsoft.com/.default" };
var result = await app.AcquireTokenForClient(scopes).ExecuteAsync();
return result.AccessToken;
}

view raw
GetMsalGraphToken.cs
hosted with ❤ by GitHub

The interesting bit here is that the token should represent the app for which we’re trying to call addKey. So we don’t need another app identity that has permissions to manage apps in the Azure AD tenant to make this call for us. In fact, that’s not even possible: this addKey action seems to be designed from the ground up to provide self-service key management functionality to registered apps. And the best thing is that the app doesn’t need any special permission for this; a newly registered app with default permissions can do this just fine.

Proof

Moving on to the request body, the proof property is the most interesting one: it’s supposed to be “A signed JWT token used as a proof of possession of the existing keys“. And this existing key “is the private key of one of the application existing certificates“. This is why certificate credentials are required for this approach. Together with some other requirements for this self-signed JWT token, the full code for constructing one looks like this:

private string GetJwtTokenProof(X509Certificate2 signingCert, string appId)
{
var notBefore = DateTime.Now;
var expires = notBefore.AddMinutes(10);
var handler = new JwtSecurityTokenHandler();
var credentials = new X509SigningCredentials(signingCert);
var jwtToken = handler.CreateJwtSecurityToken(appId, "https://graph.windows.net", null, notBefore, expires, null, credentials);
return handler.WriteToken(jwtToken);
}

view raw
GetJwtTokenProof.cs
hosted with ❤ by GitHub

Note that this code requires the System.IdentityModel.Tokens.Jwt Nuget package.

Key credential

The details regarding the request body depend on whether or not you’re using the Graph client (as opposed to manually constructing the HTTP calls, for example), but if you are, this is simply a matter a creating a KeyCredential object:

private KeyCredential CreateKeyCredential(X509Certificate2 certificate)
{
return new KeyCredential()
{
Key = certificate.RawData,
Usage = "Verify",
Type = "AsymmetricX509Cert"
};
}

Putting it all together

This is all there is to it to enable an app to make a call to Azure AD to register a new certificate for itself (or revoke one, for that matter). So it nicely fulfills our requirements: we can provision the app with a temporary certificate we create centrally, with a validity of just 1 or 2 days. Using that certificate, the app can self-sign a new certificate, use the temporary one to sign the JWT token proof to register the new one, and then use the newly registered certificate to revoke the temporary one. Equally, when a certificate is about to expire, it can use the same flow to create and register a new one and revoke the old one. The complete code looks like this:

using Microsoft.Graph;
using Microsoft.Identity.Client;
using Microsoft.IdentityModel.Tokens;
using System;
using System.IdentityModel.Tokens.Jwt;
using System.Linq;
using System.Net.Http.Headers;
using System.Security.Cryptography.X509Certificates;
using System.Threading.Tasks;
namespace AzureADAppManagement
{
public class AppCertificateManager
{
public async Task RollCertificatesAsync(string appId, string appObjectId, string tenantId, X509Certificate2 existingCertificate, X509Certificate2 newCertificate)
{
var graph = GetGraphClient(() => GetTokenAsync(appId, existingCertificate, tenantId));
var keyCredential = CreateKeyCredential(newCertificate);
var proof = GetJwtTokenProof(existingCertificate, appId);
await graph.Applications[appObjectId].AddKey(keyCredential, proof).Request().PostAsync();
// Waiting 120 secs; proceeding immediately may result in failure if the new cert is not fully processed server side
// Not sure how much time is appropriate here, to be honest. 120 secs seems excessive, but 20 secs for example has proven too short
await Task.Delay(120000);
// Re-init the client to use the new cert for token retrieval
graph = GetGraphClient(() => GetTokenAsync(appId, newCertificate, tenantId));
// Find the keyId for the old certificate
var app = await graph.Applications[appObjectId].Request().GetAsync();
var keyId = app.KeyCredentials.Single(key =>
{
return Convert.ToBase64String(key.CustomKeyIdentifier).Equals(existingCertificate.Thumbprint, StringComparison.OrdinalIgnoreCase);
}).KeyId;
// Create new proof based on the new certificate
proof = GetJwtTokenProof(newCertificate, appId);
// Remove the old certificate
await graph.Applications[appObjectId].RemoveKey(keyId.Value, proof).Request().PostAsync();
}
private GraphServiceClient GetGraphClient(Func<Task<string>> tokenDelegate)
{
return new GraphServiceClient(new DelegateAuthenticationProvider(async (requestMessage) =>
{
var token = await tokenDelegate();
requestMessage
.Headers
.Authorization = new AuthenticationHeaderValue("bearer", token);
}));
}
private async Task<string> GetTokenAsync(string appId, X509Certificate2 certificate, string tenantId)
{
var app = ConfidentialClientApplicationBuilder.Create(appId)
.WithAuthority($"https://login.microsoftonline.com/{tenantId}/")
.WithCertificate(certificate)
.Build();
var scopes = new[] { "https://graph.microsoft.com/.default" };
var result = await app.AcquireTokenForClient(scopes).ExecuteAsync();
return result.AccessToken;
}
private string GetJwtTokenProof(X509Certificate2 signingCert, string appId)
{
var notBefore = DateTime.Now;
var expires = notBefore.AddMinutes(10);
var handler = new JwtSecurityTokenHandler();
var credentials = new X509SigningCredentials(signingCert);
var jwtToken = handler.CreateJwtSecurityToken(appId, "https://graph.windows.net", null, notBefore, expires, null, credentials);
return handler.WriteToken(jwtToken);
}
private KeyCredential CreateKeyCredential(X509Certificate2 certificate)
{
return new KeyCredential()
{
Key = certificate.RawData,
Usage = "Verify",
Type = "AsymmetricX509Cert"
};
}
}
}

Why I prefer this approach

Of course there are different ways of handling credential provisioning and key rolling. For example: the application could just be provisioned with a centrally generated (symmetric or asymmetric) key that’s intended as the definitive key (during that 1 or 2 year validity period). However, this would mean that this central agent has, at some point in time, knowledge of these long-term credentials, which would increase the risk associated and therefore the measures taken to properly protect it. The same applies to key rolling: you could have the apps call into a custom-built API to signal its desire to renew its key, or you could orchestrate the key rolling process from a central agent altogether. But again, that would imply having these credentials available in a runtime that’s neither client nor Identity Provider. Furthermore, this agent would need extensive permissions on the Microsoft Graph to actually be able to register new credentials. Especially in case this agent is callable by external parties (such as a client initiating a key rolling process), you would need to make very sure that you’ve covered your bases to prevent Elevation of Privilege.

And just to reiterate: the addKey approach works without special Microsoft Graph permissions, and it only works when the call includes a Bearer token that represents the app itself, so the possible attack surface is greatly reduced. Of course you’d still need to centrally provision that initial temporary certificate, so security measures are still applicable for the agent handling that, but the keys it generates can have a very limited validity. And since it plays no part in the key rolling process, it’s not callable from the outside, and is therefore more easily secured.

So, all in all, I really like this hidden gem in the Microsoft Graph API. Let me know what you think in the comments!

HowTo: Perform “On Behalf Of” Calls Using Azure Active Directory

Probably every developer out there is familiar with the scenario of a UI-driven application (let’s say a web app) that needs to make calls to a backend service, and in quite a few of those scenarios the backend service needs to know which user is logged in in order to fullfill the request. And if you have ever been in charge of deciding on an implementation for this, you have been at the crossroads: do I go with the full-fledged impersonation / delegation solution, or do I conveniently decide that I trust the web app to make the correct calls?

If you’ve chosen the latter, you went with the so-called trusted subsystem architecture. Simply put: your backend service is treating the web app as a system that can be trusted to properly authenticate end users, and only perform backend service calls if and when appropriate, possibly including end user identifiers (such as usernames) as part of these calls.

Trusted Subsystem
The Trusted Subsystem solution

If you opted for the full-fledged impersonation and delegation solution, you probably learned very soon that this is hard. In the old on-prem enterprise world, you would have to learn about the intimate details of Kerberos Constrained Delegation. And if you were ‘lucky’ enough to be working with WIF and WS-Federation or SAML, you would find out that these protocols do support these scenarios, but still make it pulling-your-hair-out-difficult to implement. And now we’re just calling one downstream service from our web app; once we need to call yet another service from the first service, we more often than not just give up and go with the trusted subsystem approach after all.

Azure Active Directory To The Rescue

Luckily, SAML and WS-* are no longer the only protocols available. OAuth 2.0 and OpenID Connect have been gaining momentum for some time now, and are treated as first class citizens in the latest Identity & Access Management solutions that Microsoft is offering, especially Azure Active Directory. To add to that, Microsoft has provided a client-side library called ADAL (Active Directory Authentication Library) for a variety of platforms (including AngularJS and iOS for example) to simplify interaction with Azure Active Directory as much as possible.

And the good news is: even impersonation and delegation has gotten really simple, with a lot less moving parts on the client. (Everyone who has ever struggled with config files trying to get this to work using WS-* and WIF knows exactly what I mean…)

The guys at Microsoft are also putting a lot of effort into code samples on Github that show how to use Azure AD and ADAL to get all sorts of scenarios working.

image

The On Behalf Of scenario is also available on there. It’s a native client that calls an API, which in turn calls the Graph API on behalf of the logged in user. Obviously, the native client app can be substituted for an ASP.NET Core MVC web app, as shown in this repo.

Not every platform-scenario-combo is available. For example, the API calling another API scenario (i.e. the On Behalf Of scenario) is not available in its ASP.NET Core incarnation. And since the code to achieve this for ASP.NET Core Web API is not readily deducible from the native client sample that is only available with a ASP.NET Web API, I’d like to share some of it here.

First of all, the middleware to wire up an ASP.NET Core Web API to actually consume tokens is a bit different from how it used to be done. You can take you queue from the aforementioned repo; just make sure to save the token you receive so that you can access it later:

app.UseJwtBearerAuthentication(new JwtBearerOptions
{
    AutomaticAuthenticate = true,
    AutomaticChallenge = true,
    Authority = String.Format(Configuration["AzureAd:AadInstance"], Configuration["AzureAD:Tenant"]),
    Audience = Configuration["AzureAd:Audience"],
    SaveToken = true
});

Actually using this token to bootstrap the On Behalf Of flow works like this:

var authority = [insert authority here];
var clientId = [insert client ID here];
var clientSecret = [insert client secret here];
var resourceId = [insert the resource ID for the called API here];

AuthenticationContext authContext = new AuthenticationContext(authority);
ClientCredential credential = new ClientCredential(clientId, clientSecret);
AuthenticateInfo info = await HttpContext.Authentication.GetAuthenticateInfoAsync(JwtBearerDefaults.AuthenticationScheme);
var token = info.Properties.Items[".Token.access_token"];
var username = User.FindFirst(ClaimTypes.Upn).Value;
var userAssertion = new UserAssertion(token, "urn:ietf:params:oauth:grant-type:jwt-bearer", username);
AuthenticationResult result = await authContext.AcquireTokenAsync(resourceId, credential, userAssertion);

The AuthenticationResult that ADAL is returning here contains an Access Token that can be used to call the downstream Web API. Simple, right? OK, it involves some code, but it’s pretty straighforward when compared to a WS-*-and-a-WCF-service scenario I wrote about earlier.

Enter Microservices

As said before, we’ve all encountered On Behalf Of scenarios and the perils of getting them to work using SAML, WS-* or Kerberos, and more often than not we gave up on the full-fledged scenario. But in an increasingly API-centered world, we are calling other external services much more frequently than we did only a couple of years ago. And now that microservices gains a lot of momentum as an architectural style, this frequency increases even more since fulfilling a user request in a microservices environment is pretty much always a matter of multiple services collaborating.

Advocates of microservices recognize that flowing user identities through services is a concern that deserves more attention in a microservices architecture. Sam Newman, for example, discusses this issue in his book Building Microservices, in a paragraph aptly titled “The Deputy Problem”.

He recognizes the ease of use that comes with OpenID Connect and OAuth 2.0. And while he is still somewhat skeptical about whether these protocols will make it into the mainstream market any time soon, for all you dev’s out there that are on the Microsoft ecosystem, this is not a concern anymore.

Extending The Scenario

Obviously, we want to do more than simply impersonate end users when calling downstream services. Especially in a microservices environment, where multiple clients are calling multiple services for even the most mundane of tasks, we may want to have varying levels of trust: “Sure, I’d be more than happy to perform this request for the user, but only if he is calling me through an application that is entrusted to make these types of delegated calls.” In order words, you may want to base your authorization decisions on characteristics of both the end user and the calling app.

Azure Active Directory is capable of handing these types of scenarios as well, for example by using scopes. I’m not getting into those now, but I’ll be teaming up with my colleague Jurgen van den Broek for a session at the Dutch TechDays 2016, in which we will cover these and a lot more scenarios – including a peek into the future by discussing what the AAD v2 endpoint brings to the table.

Immediately after the TechDays session, I’ll update this post with a link to the full code sample. So stay tuned, and feel free to post a comment if you need help in the meantime.

Blast from the Past: A Delegation Scenario using WS-Federation and WS-Trust

A couple of weeks ago, I wanted to outline some of the different flavors and protocols available for delegation scenarios using a federated identity. One of the protocols on my list was WS-Federation and WS-Trust. Yes, I know, all the cool kids are doing OpenID Connect these days, but some of us are working for enterprises that bought into the whole federation-thing rather early and while still on-premise. For those environments ADFS is most likely the Identity Provider. And if the relying parties are .NET-based apps, the protocol of choice for identity federation is WS-Federation.

Of course, I did want to use the latest and greatest as much as possible, so I checked out the new OWIN/Katana gear for WS-Federation. And sure enough, getting identity federation to work using ADFS as the Identity Provider was a breeze. However, delegating the federated identity to a backend WCF service: not so much…

The theory here is that, firstly, the WCF service is also registered as a relying party in ADFS; secondly, that the web application is allowed to delegate identities to that relying party; and thirdly, that the web application can use the ADFS-issued user token to send back to ADFS as part of the request for a delegation token. Now the issue I encountered is that the token, as persisted by the OWIN middleware, does not have the same format as is expected by the time the delegation call is being made. More specifically, the token is persisted as a string, whereas the delegation code is expecting a SecurityToken.

I’ve tried to work this out in just about every way I could think of. This was not exactly made easier by the utter lack of online resources when it comes to WS-Federation (especially in its .NET 4.5 and OWIN incarnations). Still, I did not get this to work using the OWIN middleware. So I defaulted back to the ‘classic’ way of making this work, configuring the initial federation with ADFS through the web.config for both the front end MVC application and the backend WCF service that the web app is calling into. And as said, the online resources on WS-Federation in .NET 4.5 are limited, so I figured I’d share my sample on Github.

There’s a lot of moving parts to this sample, and principles to grasp if you want to fully understand the code. Luckily, all of that is pretty much covered in this guide. The ADFS part of it is pretty accurate as it is, and even though it is aimed at ADFS 2.0, it’s easily transferable to ADFS 3.0. As far as the code goes, the principles remain the same but the implementation is based on WIF on .NET 4.0. So you’ll have to do some digging through my sample to match it to the way it is described in the guide. Just see it as a learning opportunity ;).

I will reveal one difference: the guide assumes that the account running the web application is domain-joined so the web app can authenticate itself to ADFS using Windows Authentication when it makes the call to get the delegation token. To simplify the setup, I chose to authenticate to ADFS using a username and password so that I wouldn’t have to set up Kerberos. To make the username-based binding work, I used Dominick Baier’s UserNameWSTrustBinding. This was available in WIF on 4.0 but did not make it into 4.5, so Dominick added it to his Thinktecture.IdentityModel NuGet package.

Oh, and don’t expect the sample to be production ready. In fact, it won’t even work out of the box when you run it. You will have to configure several URL’s to match you environment. And as said, you’ll have to configure ADFS using the tutorial I mentioned.

Of course, I haven’t totally given up on the OWIN route, nor am I finished outlining the different delegation flavors. So stay tuned, because there’s more to come on coding identity federation and delegation!