Using API Management user subscription keys in the back-end API App

Azure API Management gives you the tools you need for end-to-end API management like provisioning user roles, creating usage plans and quotas, applying policies for transforming payloads and for example setting up throttling.
So it’s a great way to add extra security on top of a web API. The API Management gateway in Azure and the back-end service even don’t have to be connected to each other. But what if you want to know in the back-end web API which user from API Management calls the API? This may be necessary for example if you need to implement logic that a specific user can only see its own data.

When a developer in API Management subscribes to a product he is granted a primary and secondary subscription key for the product. This key is used when making calls into the product's APIs. Luckily its also forwarded to the the underlying web API and therefore can be used for your own purposes.

The following steps are necessary to use the API Management subscription key in the underlying API.

• Create code in API App to store the subscription key
• Publish the API App to Azure
• Import the API App in Azure API Management
• Call the API App from the API Management Developer Portal

Create code in API App to store subscription key

To show how to store the developer subscription key I’m going to modify the OrdersAPI sample that I have created in my previous blog post.

public class ServerOrder
{
    [JsonProperty(PropertyName = "id")]
    public string Id { get; set; }
    public Customer customer { get; set; }
    public Item item { get; set; }
    public string OrderStatus { get; set; }
    public DateTime ModifiedDate { get; set; }
    public DateTime CreationDate { get; set; }
    public string SubscriptionKey { get; set; }         
}

public async Task<string> CreateOrder(ClientOrder order, string subscriptionKey)
{
    string id = null;

    //Create a server order with extra properties
    ServerOrder s = new ServerOrder();

    s.customer = order.customer;
    s.item = order.item;

    //Add meta data to the order
    s.OrderStatus = "in progress";
    s.CreationDate = DateTime.UtcNow;
    s.SubscriptionKey = subscriptionKey;

    //Get a Document client
    using (client = new DocumentClient(new Uri(endpointUrl), authorizationKey))
    {

        string pathLink = string.Format("dbs/{0}/colls/{1}", databaseId, collectionId);
        
        ResourceResponse<Document> doc = await client.CreateDocumentAsync(pathLink, s);

        //Return the created id
        id = doc.Resource.Id;
    }
    return id;
}

public async Task<IHttpActionResult> Post([FromBody]ClientOrder order)
{
    OrderResult result = new OrderResult();

    IEnumerable<string> headerValues;
    string subscriptionKey = null;

    if (Request.Headers.TryGetValues("Ocp-Apim-Subscription-Key", out headerValues))
    {
        subscriptionKey = headerValues.FirstOrDefault();
    }

    if (subscriptionKey != null)
    {
        OrderManager mgr = new OrderManager();
        string id = await mgr.CreateOrder(order, subscriptionKey);

        if (id != null)
        {
            result.Id = id;
        }

        // Return a HTTP 200 with the created id
        return Ok(result);
    }
    else
    {
        // Return HTTP 401 Unauthorized 
        throw new HttpResponseException(HttpStatusCode.Unauthorized);
    }
}

Publish the API App to Azure

This blog port does not describe how to publish an API App to Azure but only focuses on the specific steps that are necessary to make this sample work. See Get started with API Apps for how to create and publish an API App.

In your browser address bar go to the URL of the API app and add swagger to the end of the line. Copy the URL in the Swagger field. This is the default URL used by Swashbuckle to return Swagger JSON metadata for the API.

Import the API App in Azure API Management

This blog port does not describe how to set up API Management in Azure but only focuses on the specific steps that are necessary to make this sample work. See Manage your first API in Azure API Management for how to set up API Management in Azure.

The generated Swagger metadata from the previous step makes it easy to import the API App in Azure. Go to the API Management Dashboard and click on “Import API”.

Use the URL with the Swagger metadata from the API App to import the API App in API Management.

Call the API App from API Management Developer Portal

The API App can be called directly from the Developer Portal, which provides a convenient way to view and test the operations of the API.

Enter the Request Body and click on the Send button. The "Ocp-Apim-Subscription-Key" key is automatically added to the header of the request.

After the POST operation is invoked, the developer portal displays a HTTP 200 status with the created id if the body and the header of the request is correct.

Check in the Azure Portal with the Document Explorer if the order and the SubscriptionKey really is stored in DocumentDB.

Wrap Up

The API Management Subscription key which provides access to an API can also easily be used in the underlying web API. This can be very useful you want to know in the back-end API which user from API Management calls the API.