Monetize your APIs with Azure API Management

In a world of Microservices and APIs, it might come a time when you realize you have some service that others might want to use.

Azure API Management was made for this purpose, to centralize the management of all your APIs.

It allows an easy tracking of usage, thanks to its subscription-key approach, with a unique key per user; so you can easily charge money to use your APIs.

But one caveat is that the user base in API Management is a "standalone" list, not necessarily aligned with Azure Active Directory (where you probably will have already all your users).

So if you want to align these two worlds, as of now you need to be creative, bend some concept, and implement a few tricks, as explained here.

Let's start from the basic, that is how Azure Active Directory works behind the scenes.

Here you can see the basic entities of Azure Active Directory for an Application: the App Registration and the Enterprise Applications; from these two entry points in the Azure portal you can manage almost everything about your App authentication.

Now, if you want to have some Customer specific division in your Azure Active Directory, you need to be a bit creative, and mis-use some entity to achieve your needs (I was hoping that AAD B2B or B2C would help achieving this, but apparently that is not the case so far).

As you can see in the above picture, you define CustomerA and CustomerB in AAD as Security Groups; then you can add to these group all the users from each Company, which you previously invited to your AAD as described here.

At this point you edit your Application Manifest in the AAD Registration and add two new AppRoles: CustomerA and CustomerB.

Then you open the Enterprise Applications menu of the AAD section in the Azure portal, and assign those new AppRoles to your users individually (behind the scenes through a AppRoleAssignment).

Now, since you use API Management, you need an App Registration in AAD also for its Developer portal (this is where your API consumers will login in order to learn about and test your APIs).

Once you did that, you can switch to the API Management Publisher portal, and import your API, as described here.

You will also need to create an Authorization Server in the Publisher Portal, so that it can use the OAuth2 Permissions in AAD, as shown in the picture above.


Now, to make things a bit more complex, you need to have your API users to register on the API Management Developer portal (as of now, "invite" for some reason does not work, so you have to rely on them to do it...).

Once they did register, and you have your users in API Management, you can create the Customer Groups as you did in AAD, choosing to "Add groups from AAD". in the Product section of the API Management Publisher portal. under the Visibility tab.

Obviously you need to have a Product for each Customer, with the same names as the Groups you previously created. That will allow for an easy match and assignment without confusion, as you can see in the picture here below.

Once you performed all these steps, you are now able to use Role-Based Authorization as usual at your Operation (action or method) level in your APIs, as shown here below.

Limit access to this Operation only to CustomerA users:

Limit access to this Operation only to CustomerB users:

Allow access to this Operation to both CustomerA and CustomerB users:

And thanks to the API Management Analytics section in the Publisher portal, you can see all details about usage of your APIs, by user, as well as Customer.

Now, the only work left for all this to be really useful and easy, is to automate it, of course!

Luckily API Management provides a REST API that you can use, more or less like the Azure Graph API.

But I will tell you about it in a next post.

;)

For now, Happy Holidays!

Run your API behind Azure API Management

In order to run your API behind Azure API Management there are a few important steps to take.

You first open the API Management Publisher Portal, this can be done from the Azure Portal by selecting API Management services and your service instance.

If you did not create yet your instance, refer to this article.

Import API

If you want to import your API (rather than creating everything manually), it is essential that you have a correct Swagger definition. I wrote a post about it, so if not sure, have a look here.
You can import definitions in the Swagger, WADL and WSDL format.

Assign a Product

Once you imported the API in API Management, you need to assign it to a Product, so users can subscribe to it and obtain their personal Subscription Key, required to access your API.

You can either use the existing Starter or Unlimited, or create a new one.

Setup Authorization Server

Now you can create the Authorization Server that you will use in the Developer Portal of API Management. Once created, you can assign it to your API.

Azure Active Directory Developer Portal App Registration

You will need to take care of the Azure Active Directory App Registration as well, also in the above link. In particular make sure that you add the Authorization Code Grant URL generated by the Authorization Server to the ReplyURLs list of the AAD App Registration for the API Management Developer Portal; you also need to add the Application ID and created secret Key of the API Management Developer Portal to the Client Credentials fields as shown here.

While there, under the Permissions menu blade, select your Backend API and all the appropriate permissions for the Developer Portal.

Setup SSL Certificate

If you use Mutual Client Authentication with SSL Certificate, you will need to upload your certificate to API Management, and assign it to your API in the Security section. Once you did that, you can verify in the API Management Policies section that you have an Inboud policy to provide your certificate's Thumbprint to your API.
Then you might want to add your Certificate Validation IAuthorizationFilter to your API, where you can check anything you want from the SSL Certificate (sample code here).

Setup C.O.R.S.

You might want to add another policy in API Management to allow C.O.R.S., depending on your API clients. You can simply select the CORS policy in the list.

Test in Developer Portal

If everything is done properly you should now be able to open the API Management Developer Portal and test your API, providing automatically the correct Subscription Key, and obtaining the OAuth2 Token from the created Authorization Server.

Devil is in the (Owin/Katana Redirect) Details

Some time ago I wrote about a bug that took a month to be solved, involving a 401 - Unauthorized Access to an Azure AppService.

After lots of troubleshooting, that issue got a solution from Microsoft support with a little code snippet that handles the AAD redirection at run-time, rather than relying on the config file value.

Turns out that this code snippet caused another issue, namely a Owin/Katana bug.

This time the same AppService (that runs just fine on Azure), cannot run anymore locally under IIS, as it generates an infinite redirect loop between the Azure login page and the AppService.

After another month of troubleshooting with Microsoft support, bouncing from one team to another (AppService, IIS, AAD, you name it), they finally were able to reproduce the core issue, which eventually got acknowledged as an official bug (I will update this post with the link to it as soon as I will receive it from Microsoft support):

Symptom:
The MVC project stopped working in IIS 10, and was entering into an infinite loop.
Cause:
There is a problem with OWIN and IIS when specifying either a CallbackPathURL or a Redirect URI. After the authentication happens > OWIN receives the response and drops the cookie > because of that the user is being set as “Not Authenticated”, as there is no cookie to trace the session that just happened. At that point is when the infinite loop starts. There is a problem with Microsoft.Owin.Host.SystemWeb and is being considered as a bug and being investigated. Seems that when mixing usage like HttpContext.GetOwinContext().Response.Cookies and HttpContext.Response.Cookies in some cases OWIN cookies are "lost".

Resolution:
For now as a work-around if you could not specify any callbackPath or Redirect URI in the request and let Azure decide where to send the response it will work just fine for your project in IIS.


So, long story short: if you have multiple Domains in your Azure AppService, and you implement the code snippet shown before, you have to remove the "RedirectUri" and "CallbackPath" from the default "OpenIdConnectAuthenticationOptions" created for you by the ActiveDirectory Client NuGet package, and then you can run your AppService locally under IIS as usual.

In the picture below you can see the red lines over the code to be removed, and the blue line around the code snippet to fix the issue reported here.