Securing APIs by Using Subscriptions

Securing your APIs is essential to ensure that only authorized applications can connect to your services. Azure API Management employs subscription keys as a primary way to control API access. This guide explains how subscription keys work, their various scopes, and how to manage them through the Azure API Management portal.

Subscription Key Scopes

Azure API Management allows you to apply subscription keys at different scopes to suit your access control needs:

1. All APIs Scope:
   The subscription key provides access to every API available through the gateway. This simplifies management when you want a single key to cover your entire API portfolio.

2. Single API Scope:
   The subscription key is limited to a specific API and all its endpoints. This approach is ideal for restricting access to selected APIs.

3. Product Scope:
   A product is a grouping of APIs with shared access rules, usage quotas, and terms of use. Subscription keys at the product level are particularly useful for managing bundled service offerings.

Managing Subscription Keys in the API Management Portal

When you make a request to a secured API, the subscription key must be included for authentication. Without it, attempts to access protected resources (for example, using Postman to retrieve flight logs) will fail.

You can regenerate subscription keys at any time from the Azure portal. Regular key regeneration is a best practice to maintain security, especially if a key is compromised.

Each subscription includes both primary and secondary keys to enable seamless key rotation. For instance, you can switch to the secondary key while regenerating the primary key to ensure uninterrupted API access.

Authenticating API Requests with Subscription Keys

To authenticate API requests, include the subscription key as either a request header or a query string parameter. By default, Azure API Management expects the key to be passed in the header named OCP-Apim-Subscription-Key.

Azure API Management also features a developer portal that allows you to test API calls, ensuring your subscription key is properly integrated before the API goes live.

Demonstration in the Azure Portal

To manage subscription keys in the Azure portal:

1. Navigate to your API Management instance.
2. Select the "Subscriptions" section to view both product-level keys and service-level keys that grant access to all APIs.
3. Click "Add Subscription" to create a new subscription. Provide a name (for example, "Flight API") and select the appropriate scope.

For example, you might choose the "Specific API" option and select the "Flight Logs API." After creating the subscription, click on "Show/Hide Keys" to view the primary key. You will then integrate this key in your API calls, either as a header with the name OCP-Apim-Subscription-Key or as a query string parameter.

Testing API Calls with Postman

When testing your API using tools like Postman, be sure to include the subscription key. A valid request returns a response similar to the following JSON:

[
    {
        "flightNumber": 1566,
        "departureAirportCode": "LIZ",
        "arrivalAirportCode": "CHW",
        "departureDatetime": "2022-12-13T08:00:00",
        "arrivalDatetime": "2022-12-13T10:00:00",
        "airlineName": "united",
        "flightDurationMinutes": 1332
    },
    {
        "flightNumber": 5377,
        "departureAirportCode": "TBM",
        "arrivalAirportCode": "BBU",
        "departureDatetime": "2022-06-05T06:00:00",
        "arrivalDatetime": "2022-06-05T08:00:00",
        "airlineName": "united",
        "flightDurationMinutes": 1399
    },
    {
        "flightNumber": 3034,
        "departureAirportCode": "TXN",
        "arrivalAirportCode": "LLM",
        "departureDatetime": "2022-09-14T08:00:00",
        "arrivalDatetime": "2022-09-14T10:00:00",
        "airlineName": "united",
        "flightDurationMinutes": 1210
    }
]

Conclusion

Subscription keys are an integral part of securing and managing access to your APIs using Azure API Management. Whether you decide to use a single key for all APIs, restrict access to a specific API, or manage a suite of APIs via a product, subscription keys offer flexible and robust control over your endpoints. Combined with features like key rotation and the developer testing portal, they make managing API security straightforward and efficient.

For more details on best practices and additional security options, refer to the Azure API Management documentation.