Developer toolkit for working with Azure AD B2C JWT-protected APIs

Published on
Reading time
Authors

I've blogged in the past about Azure Active Directory B2C and how you can use it as a secure turnkey consumer identity platform for your business.

In this post I'm going to walk through how you can debug JWT-protected APIs where those JWTs are being issued by AAD B2C. Note that a lot of what I write here will probably be applicable in any scenario where you are working with JWTs as AAD B2C is standards compliant so any advice here can be applied elsewhere.

We aren't going to get into the Identity Experience Framework (IEF) here because he's a whole universe of detail beyond the basic policy engine we'll cover here :)

Your toolikit

Here's the tools to get started with debugging.

Required tools:

Optional, but recommended:

  • jwt.ms (there is also jwt.io if you prefer)
  • Mailinator or any number of alternatives.
  • Create a B2C Profile Edit Policy even if you never roll it out to customers. This policy can be invoked via the Azure Portal to allow you to initialise new profile attributes.

Use standard OAuth libraries in your clients

Microsoft has great first-party support for B2C with the Microsoft Authentication Library (MSAL) across multiple platforms, but as B2C is designed to be an OAuth2 compliant service so any library that supports the specification should work with B2C. Microsoft provides samples that show how libraries like AppAuth can be used.

Rolling out custom attributes

There is currently a limitation with B2C around rolling out new custom attributes. Until an attribute is referenced in at least once policy in your tenant the attribute isn't available to applications that utilise Graph API. This is why I always create a profile edit policy even that I can add new custom attributes to and then invoke the policy via the Azure Portal to initialise the attribute.

Testing APIs

Create test users

This is where a service like Mailinator comes in handy - you can create multiple test users and easily access the email notifications sent by B2C to perform actions like initial account validation or password reset.

Note: free services like Mailinator may be good for simple testing, but you may have security or compliance requirements that mean it can't be used. In that case consider moving to a paid tier or other services that provide secured mailboxes (a service like outlook.com).

Request Tokens - Test Client Application

Once you have one or more test users you can then use one of the following approaches to obtain test tokens to use when calling APIs.

If you aren't using Postman to retrieve tokens to supply in API calls then you can use the test client application above (assuming you are developing on Windows - or at some future point when we get WPF ported to .Net Core :)) to request tokens for users in your test tenant.

B2C Test Tool

Once you have the tokens you can copy them out and use them in Postman to make requests against your API by setting Authorization in Postman to use Bearer Tokens and then copying the value from the test tool into the 'Token' field.

Postman using a Token

If you've having issues with tokens being accepted by your API then you can leverage jwt.ms to review the contents of the token and see why it might be being rejected. A sample is shown below.

jwt.ms sample

If you have access to the target API source code make sure to debug that at the same time to see if you can identify why the token is being rejected.

As a guide the common failure reasons will include: token expired (or not yet valid); scopes are incorrect (if used); incorrect issuer (misconfiguration of client or API where they are not from the same B2C tenant); invalid client or audience ID.

So there we are! I hope you found this post useful in debugging B2C APIs - I certainly wish that I'd had something to reference when I started developing with B2C! Now I do! 😜