Intro

API Management helps organizations publish APIs to external, partner, and internal developers to unlock the potential of their data and services

Documentation

• https://azure.microsoft.com/en-us/services/api-management/

• Documentation: https://docs.microsoft.com/en-us/azure/api-management/

• Tutorial: Import and publish your first API

• API Management access restriction policies

• Create subscriptions in Azure API Management

• Use managed identities in Azure API Management

• Learning Path: Architect API integration in Azure

• API Management Evaluation: https://wilsonmar.github.io/api-management-evaluation/

Tips and Tidbits

• Azure API Management acts as a gateway between your web APIs and the public internet.

• An Azure API gateway is an instance of the Azure API management service.

• The API gateway is the endpoint that:

  • Accepts API calls and routes them to your backends.

  • Verifies API keys, JWT tokens, certificates, and other credentials.

  • Enforces usage quotas and rate limits.

  • Transforms your API on the fly without code modifications.

  • Caches backend responses where set up.

  • Logs call metadata for analytics purposes.

• The Developer portal serves as the main web presence for developers, where they can:

  • Read API documentation.

  • Try out an API via the interactive console.

  • Create an account and subscribe to get API keys.

  • Access analytics on their own usage.

• Developers are the customers that build applications using your APIs.

  • Developers are granted access to the developer portal and build applications that call the operations of an API.

• Policies are a powerful capability of API Management that allow the Azure portal to change the behavior of the API through configuration.

• Policies are a collection of statements that are executed sequentially on the request or response of an API.

  • Popular statements include format conversion from XML to JSON and call rate limiting to restrict the number of incoming calls from a developer.

  •  

• The name you use for the gateway must be globally unique within the .azure-api.net namespace.

• When you publish APIs through Azure API Management, it's easy and common to secure access to those APIs by using subscription keys.

  • A “subscription” in this context is not referring to an Azure Subscription.

    • Subscriptions in Azure API Management

• Client applications that need to consume the published APIs must include a valid subscription key in HTTP requests when they make calls to those APIs.

For developers, API Management provides a range of benefits.

• API documentation. Documentation of APIs enables calling clients to quickly integrate their solutions. API Management allows you to quickly expose the structure of your API to calling clients through modern standards like Open API. You can have more than one version of an API. With multiple versions, you can stage app updates as your consuming apps don't have to use the new version straight away.

• Rate limiting access. If your API could potentially access a large amount of data, it's a good idea to limit the rate at which clients can request data. Rate limiting helps maintain optimal response times for every client. API Management let you set rate limits as a whole or for specific individual clients.

• Health monitoring. APIs are consumed by remote clients. So it can be difficult to identify potential problems or errors. API Management lets you view error responses and log files, and filter by types of responses.

• Modern formats like JSON. APIs have used many different data exchange formats over the years from XML to CSV and many more. API Management enables you to expose these formats using modern data models like JSON.

• Connections to any API. In many businesses, APIs are located across different countries and use different formats. API Management lets you add all of these disparate APIs into single modern interface.

• Analytics. As you develop your APIs, it's useful to see how often your APIs are being called and by which types of systems. API Management allows you to visualize this data within the Azure portal.

• Security. Security is paramount when dealing with system data. Unauthorized breaches can cost companies money, time lost in reworking code, and reputational loss. Security tools that you can use with Azure API management include OAuth 2.0 user authorization, and integration with Azure Active Directory.

Secure APIs by using subscriptions

• Secure APIs by using subscriptions

  • it's easy and common to secure access to those APIs by using subscription keys.

  • API Management also supports other mechanisms for securing access to APIs, including: OAuth2.0, Client certificates, and IP allow listing.

• Subscriptions give you granular control over permissions and policies.

• The three main subscription scopes are:

• Call an API with a subscription key

• When you publish an API, you often want some level of control over who can access the API through the gateway.

  • Subscription keys are used to restrict access to an API.

• To get a subscription key for accessing APIs, a subscription is required. 

• After you create the subscription, two API keys are provided to access the APIs.

  • One key is primary, and one is secondary.

  • API subscription keys are not automatically saved to Azure Vault

• A subscription key is a unique auto-generated string which needs to be passed through in the headers of the client request.

• The key is directly related to a subscription which can be scoped to different areas, this gives granular control over permissions and policies.

• The three main subscription scopes are:

  • All APIs

  • A Single API

  • A product

• Applications that call a protected API must include the key in request calls.

• You can regenerate these subscription keys at any time, for example, if you suspect that a key has been shared with unauthorized users.

• Every subscription has two keys, a primary and a secondary. Having two keys makes it easier when you do need to regenerate a key.

• Applications must include a valid key in all HTTP requests when they make calls to API endpoints that are protected by a subscription.

• Keys can be passed in the request header, or as a query string in the URL.

  • The default header name is Ocp-Apim-Subscription-Key, and the default query string is subscription-key.

    curl --header "Ocp-Apim-Subscription-Key: <key string>" https://<apim gateway>.azure-api.net/api/path curl https://<apim gateway>.azure-api.net/api/path?subscription-key=<key string>

• To use an API, developers subscribe to a product that contains that API, and then call the API's operation.

• A product is a collection of one or more APIs that you configure in APIM. You can assign APIs to more than one product. Products can have different access rules, usage quotas, and terms of use.

Secure APIs by using certificates

• Secure APIs by using certificates

• Certificates can be used to provide Transport Layer Security (TLS) mutual authentication between the client and the API gateway.

• You can configure the API Management gateway to allow only requests with certificates containing a specific thumbprint.

• The authorization at the gateway level is handled through inbound policies.

• With TLS client authentication, the API Management gateway can inspect the certificate contained within the client request

API Gateway

• Explore API gateways

• An API gateway sits between clients and services.

  • It acts as a reverse proxy, routing requests from clients to services.

  • It may also perform various cross-cutting tasks such as authentication, SSL termination, and rate limiting.

• If you don't deploy a gateway, clients must send requests directly to front-end services.

Open

• Potential problems with exposing services directly to clients:

  • It can result in complex client code.

    • The client must keep track of multiple endpoints, and handle failures in a resilient way.

  • It creates coupling between the client and the backend.

    • The client needs to know how the individual services are decomposed. That makes it harder to maintain the client and also harder to refactor services.

  • A single operation might require calls to multiple services.

    • That can result in multiple network round trips between the client and the server, adding significant latency.

  • Each public-facing service must handle concerns such as authentication, SSL, and client rate limiting.

  • Services must expose a client-friendly protocol such as HTTP or WebSocket.

    • This limits the choice of communication protocols.

  • Services with public endpoints are a potential attack surface, and must be hardened.

• Gateway routing: Use the gateway as a reverse proxy to route requests to one or more backend services, using layer 7 routing.

  • The gateway provides a single endpoint for clients, and helps to decouple clients from services.

• Gateway aggregation: Use the gateway to aggregate multiple individual requests into a single request.

  • This pattern applies when a single operation requires calls to multiple backend services.

    • The client sends one request to the gateway.

    • The gateway dispatches requests to the various backend services, and then aggregates the results and sends them back to the client.

    • This helps to reduce chattiness between the client and the backend.

• Gateway Offloading: Use the gateway to offload functionality from individual services to the gateway, particularly cross-cutting concerns.

  • It can be useful to consolidate these functions into one place, rather than making every service responsible for implementing them.

• Functionality that could be offloaded to a gateway:

  • SSL termination

  • Authentication

  • IP allow/block list

  • Client rate limiting (throttling)

  • Logging and monitoring

  • Response caching

  • GZIP compression

  • Servicing static content

API Management Tiers

• Feature-based comparison of the Azure API Management tiers

API Management backend authentication policies

• API Management authentication policies

• There are 3 options for authenticating the API management with the backend app

  • Authenticate with Basic - Authenticate with a backend service using Basic authentication.

  • Authenticate with client certificate - Authenticate with a backend service using client certificates.

  • Authenticate with managed identity - Authenticate with the managed identity for the API Management service.

• Use the authentication-basic policy to authenticate with a backend service using Basic authentication.

  • This policy effectively sets the HTTP Authorization header to the value corresponding to the credentials provided in the policy.

    • <authentication-basic username="username" password="password" />

• Use the authentication-certificate policy to authenticate with a backend service using a client certificate.

  • The certificate needs to be installed into API Management first and is identified by its thumbprint or certificate ID (resource name).

    • If the certificate references a certificate stored in Azure Key Vault, identify it using the certificate ID.

      • When a key vault certificate is rotated, its thumbprint in API Management will change, and the policy will not resolve the new certificate if it is identified by thumbprint.

    • <authentication-certificate certificate-id="544fe9ddf3b8f30fb490d90f" />

    • Secure backend services using client certificate authentication in Azure API Management

    • The certificate is converted to a X-ARR-ClientCert header.  There are some more details here   . That header should be passed through APIM. How it is accessed on the server side depends on the server framework.

      If it is ASP.NET Web API then you can do as mentioned in the below doc 

• Use the authentication-managed-identity policy to authenticate with a backend service using the managed identity.

  • This policy essentially uses the managed identity to obtain an access token from Azure Active Directory for accessing the specified resource.

  • After successfully obtaining the token, the policy will set the value of the token in the Authorization header using the Bearer scheme.

• The Target is either an Azure Logic App or HTTP(s) endpoint

Open

OAuth 2.0 authorization for API Management

• How to authorize developer accounts using OAuth 2.0 in Azure API Management

• Protect a web API backend in Azure API Management using OAuth 2.0 authorization with Azure Active Directory

• Great tutorial. OAuth 2.0 Authorisation with the Client Credentials Flow on Azure API Management <== DOTHIS

• Many APIs support OAuth 2.0 to secure the API and ensure that only valid users have access, and they can only access resources to which they're entitled.

• Configuring OAuth 2.0 user authorization in the test console of the developer portal provides developers with a convenient way to acquire an OAuth 2.0 access token

• From the test console, the token is simply passed to the backend with the API call. Token validation must be configured separately - either using a JWT validation policy, or in the backend service.

• This topic shows examples using Azure Active Directory as an OAuth 2.0 provider.

  • Protect a web API backend in Azure API Management using OAuth 2.0 authorization with Azure Active Directory

  • This feature is available in the Developer, Basic, Standard, and Premium tiers of API Management.

• A grant type (flows) refers to a way for a client application (in this context, the test console in the developer portal) to obtain an access token to your backend API. You may configure one or more grant types, depending on your OAuth 2.0 provider and scenarios.

• For more information about grant types, see the OAuth 2.0 Authorization Framework and OAuth grant types

• Authorization endpoint URL. For Azure Active Directory, this URL will be similar to the following URL, where <tenant_id> is replaced with the ID of your Azure AD tenant.

  • https://login.microsoftonline.com/<tenant_id>/oauth2/authorize

• How to include additional client data

In case you need to store additional details about a client that don't fit into the standard parameter set the custom data parameter comes to help:

The data parameter permits arbitrary content packaged in a JSON object. To set it you will need the master registration token or a one-time access token with a client-reg:data scope.

• How to inject custom data into the 'state' parameter in an OpenID Connect MVC Application

  • It’s often desirable for an Azure Active Directory (Azure AD)- integrated application to maintain application state when sending request to Azure AD for login. The recommended way to achieve this is to use the ‘state’ parameter as defined in the OpenID Connect standards. 

  • For an ASP.NET or ASP.NET CORE web application using OpenID Connect OWIN middleware, the ‘state’ parameter is maintained automatically by the middleware when sending out an authentication request

  • The OpenID Connect OWIN middleware use .Net framework’s Data Protection API to encrypt the value stored in the ‘state’ parameter. Thinking along the same line we can use the following code in OpenIdConnectNotifications’s RedirectToIdentityProvider event to inject custom data into the ‘state’ parameter

• RFC 6749: the client MAY use the "state" request parameter to achieve per-request customization

   

• Passing parameters to Azure Active Directory authentication

Use client certificates to secure access to an API

• Use client certificates to secure access to an API

• Certificates can be used to provide TLS mutual authentication between the client and the API gateway.

• You can configure the API Management gateway to allow only requests with certificates containing a specific thumbprint. The authorization at the gateway level is handled through inbound policies.

• With TLS client authentication, the API Management gateway can inspect the certificate contained within the client request and check for properties like:
  
  

• The Consumption tier in API Management is designed to conform with serverless design principles.

• If you build your APIs from serverless technologies, such as Azure Functions, this tier is a good fit.

• In the Consumption tier, you must explicitly enable the use of client certificates, which you can do on the Custom domains pane. This step is not necessary in other tiers.

API Management policies

• API Management policies

• policies are a powerful capability of the system that allow the publisher to change the behavior of the API through configuration.

• Policies are a collection of Statements that are executed sequentially on the request or response of an API.

• Policies are applied inside the gateway which sits between the API consumer and the managed API.

  • The gateway receives all requests and usually forwards them unaltered to the underlying API.

  • However a policy can apply changes to both the inbound request and outbound response.

• The policy definition is a simple XML document that describes a sequence of inbound and outbound statements

• The configuration is divided into inbound, backend, outbound, and on-error.

• The series of specified policy statements is executes in order for a request and a response.

• Create advanced policies

  • Control flow - Conditionally applies policy statements based on the results of the evaluation of Boolean expressions.

    • Policy statement(s) enclosed within the first <when/> element with condition attribute equals true will be applied.

    • Policies enclosed within the <otherwise/> element, if present, will be applied if all of the <when/> element condition attributes are false.

  • Forward request - Forwards the request to the backend service.

    • The forward-request policy forwards the incoming request to the backend service specified in the request context.

  • Limit concurrency - Prevents enclosed policies from executing by more than the specified number of requests at a time.

  • Log to Event Hub - Sends messages in the specified format to an Event Hub defined by a Logger entity.

    • the policy is used for saving selected request or response context information for online or offline analysis.

  • Mock response - Aborts pipeline execution and returns a mocked response directly to the caller.

    • It generates sample responses from schemas, when schemas are provided and examples are not.

    • If neither examples or schemas are found, responses with no content are returned.

  • Retry - Retries execution of the enclosed policy statements, if and until the condition is met. Execution will repeat at the specified time intervals and up to the specified retry count.
    
    

• Visit API Management policies for more policy examples.

• Error handling in API Management policies

• Send request context information to the backend service

API Management caching policies

• API Management caching policies

• Built-in cache is volatile and is shared by all units in the same region in the same API Management service.

• Response caching policies

  • Get from cache - Perform cache look up and return a valid cached responses when available.

  • Policy sections: inbound

    • Use the cache-lookup policy to perform cache look up and return a valid cached response when available.

    • This policy can be applied in cases where response content remains static over a period of time.

    • Get from cache:

    • allow-private-response-caching: When set to true, allows caching of requests that contain an Authorization header.

  • caching-type:

    • internal to use the built-in API Management cache,

      • Consumption plan does not provide internal caching:

    • external to use the external cache as described in Use an external Azure Cache for Redis in Azure API Management,

    • prefer-external to use external cache if configured or internal cache otherwise.

  • downstream-caching-type:

    • none - downstream caching is not allowed.

    • private - downstream private caching is allowed.

    • public - private and shared downstream caching is allowed.

  • vary-by-header:

    • Start caching responses per value of specified header, such as Accept, Accept-Charset, Accept-Encoding, Accept-Language, Authorization, Expect, From, Host, If-Match

  • vary-by-developer:

    • Set to true to cache responses per developer account that owns subscription key included in the request.

  • This policy must have a corresponding Store to cache policy.

• Store to cache - Caches responses according to the specified cache control configuration.

  • Policy sections: outbound

• Value caching policies

  • Get value from cache - Retrieve a cached item by key.

    •  

    • Policy sections: inbound, outbound, backend, on-error

  • Store value in cache - Store an item in the cache by key.

    • Policy sections: inbound, outbound, backend, on-error

    •  

  • Remove value from cache - Remove an item in the cache by key.

    • Policy sections: inbound, outbound, backend, on-error

• Custom caching in Azure API Management.

• Identify who the end user is by using the Subject claim of a JWT token.

• API Management stores the enduserid value in a context variable for later use

• Determine if a previous request has already retrieved the user information and stored it in the cache

• If there is no entry in the cache that corresponds to the key value, then no userprofile context variable is created.

  • API Management checks the success of the lookup using the choose control flow policy.

API Management transformation policies

• API Management transformation policies

• API Management policy expressions

• Use the set-backend-service policy to redirect an incoming request to a different backend than the one specified in the API settings for that operation. This policy changes the backend service base URL of the incoming request to the one specified in the policy.

• The set-status policy sets the HTTP status code to the specified value.

  •  

  • Example shows how to return a 401 response if the authorization token is invalid.

Access restriction policies

• Check HTTP header - Enforces existence and/or value of a HTTP header.

• You can use throttling to limit access to API endpoints by putting limits on the number of times an API can be called within a specified period of time.

• Limit by subscription throttling

• Limit call rate by subscription - Prevents API usage spikes by limiting call rate, on a per subscription basis.

  • The rate-limit policy prevents API usage spikes on a per subscription basis by limiting the call rate to a specified number per a specified time period.

  • When the call rate is exceeded, the caller receives a 429 Too Many Requests response status code.

  • Subscription throttling allows you to set the rate limits by a specific API operation.

    • It does not discriminate by the client.

    • Instead, every request to the API or the specified operation is throttled in the same way.

    • The problem with this type of throttling is that it allows one client to use up all the requests before another client can use it.

    • Applies to all API operations: <rate-limit calls="3" renewal-period="15" />

    • Applies to specific API operation:

• Limit by key throttling

• Key throttling allows you to configure different rate limits by any client request value.

• This type of throttling offers a better way of managing the rate limits as it applies the limit to a specified request key - often the client IP address.

• It gives every client equal bandwidth for calling the API

• Limit call rate by key - Prevents API usage spikes by limiting call rate, on a per key basis.

  • The rate-limit-by-key policy prevents API usage spikes on a per key basis by limiting the call rate to a specified number per a specified time period.

  • The key can have an arbitrary string value and is typically provided using a policy expression.

  • Configuration to limit rate limit by a requests IP Address:

• Three common ways of specifying the counter-key:

• all requests from a particular domain name to be throttled as certain domains have many calls to the API. In that case, you would specify context.Request.Headers.GetValue("host")

• Restrict caller IPs - Filters (allows/denies) calls from specific IP addresses and/or address ranges.

• Set usage quota by subscription - Allows you to enforce a renewable or lifetime call volume and/or bandwidth quota, on a per subscription basis.

• Set usage quota by key - Allows you to enforce a renewable or lifetime call volume and/or bandwidth quota, on a per key basis.

• Validate JWT - Enforces existence and validity of a JWT extracted from either a specified HTTP Header or a specified query parameter.

  • Validate JWT Policy sections: inbound

  • The validate-jwt policy enforces existence and validity of a JSON web token (JWT) extracted from either a specified HTTP Header or a specified query parameter.

  • You can use access restriction policies in different scopes for different purposes.

  • For example, you can secure the whole API with AAD authentication by applying the validate-jwt policy on the API level or you can apply it on the API operation level and use claims for more granular control.

• Validate client certificate - Enforces that a certificate presented by a client to an API Management instance matches specified validation rules and claims.

• Advanced request throttling with Azure API Management

• Protect a web API backend in Azure API Management using OAuth 2.0 authorization with Azure Active Directory

•  Configure your Azure API Management instance to protect an API, by using the OAuth 2.0 protocol with Azure Active Directory (Azure AD)

•  

1. Register an application (backend-app) in Azure AD to represent the API.

2. Register another application (client-app) in Azure AD to represent a client application that needs to call the API.

3. In Azure AD, grant permissions to allow the client-app to call the backend-app.

4. Configure the developer console in the developer portal to call the API using OAuth 2.0 user authorization.

5. Add the validate-jwt policy to validate the OAuth token for every incoming request.

• Pre-authorize requests in API Management with the Validate JWT policy, by validating the access tokens of each incoming request. If a request does not have a valid token, API Management blocks it.

API Gateway With Microservices

• Use Azure API Management with microservices deployed in Azure Kubernetes Service

• The AKS cluster and the applications that consume the microservices might reside within the same VNet, hence there is no reason to expose the cluster publicly as all API traffic will remain within the VNet.

• For these scenarios, you can deploy API Management into the cluster VNet. API Management Developer and Premium tiers support VNet deployment.

•  In this mode, the API Management gateway is injected into the cluster VNET and accessible only from within this VNet via an internal load balancer.

• There is no way to reach the API Management gateway or the AKS cluster from public internet.

• When API Management does not reside within the cluster VNet, the AKS cluster has to publish public endpoints for API Management to connect to.

  • In that case, there is a need to secure the connection between API Management and AKS. In other words, we need to ensure the cluster can only be accessed exclusively through API Management. 

Networking

• Connect to a virtual network using Azure API Management

• Azure API Management can be deployed inside an Azure virtual network (VNET) to access backend services within the network.

• For VNET connectivity options, requirements, and considerations, see Using a virtual network with Azure API Management.

• You can set up VNET connectivity for your API Management instance in the external mode, where the developer portal, API gateway, and other API Management endpoints are accessible from the public internet.

• For configurations specific to the internal mode, where the endpoints are accessible only within the VNET, see Connect to an internal virtual network using Azure API Management.

• A virtual network and subnet in the same region and subscription as your API Management instance. The subnet may contain other Azure resources.

• A network security group attached to the subnet above.

  • A network security group (NSG) is required to explicitly allow inbound connectivity, because the load balancer used internally by API Management is secure by default and rejects all inbound traffi

Create an API via CLI

Import An App’s APIs Via Azure AZ CLI

• Import-AzApiManagementApi - Imports an API from a file or a URL.

  • ^ this command replaces the AzureRM equivalent: Import-AzureRmApiManagementApi

• From WADL

• API from the specified Swagger file.

  •  

• API from the specified WADL URL link

  •  

• API from the specified OpenAPI 3.0 (Swagger) specification link

  •  

•  

Azure Functions And API Management

• Expose serverless APIs from HTTP endpoints using Azure API Management

• You can use Azure Functions and Azure API Management to build complete APIs with a microservices architecture.

• You can assemble your functions into a single API.

• The Azure API Management service enables you to construct an API from a set of disparate microservices.

• When you build an application as a collection of microservices, you create many different small services.

  • Each service has a defined domain of responsibility, and is developed, deployed, and scaled independently.

  • This modular architecture results in an application that is easier to understand, improve, and test.

  • It also makes continuous delivery easier, because you change only a small part of the whole application when you deploy a microservice.

     

• each function implements a microservice. By adding several functions to a single API Management product, you can build those microservices into an integrated distributed application

• The consumption tier aligns perfectly with serverless computing models; there's no infrastructure to manage, no idle capacity, high-availability, automatic scaling, and usage-based pricing, all of which make it an especially good choice for solutions that involve exposing serverless resources as APIs.
  
  

• The benefits of using Azure API Management to compose your API

Microservices architectures can also present challenges, such as:

• Client apps are coupled to microservices. If you want to change the location or definition of the microservice, you may have to reconfigure or update the client app.

• Each microservice may be presented under different domain names or IP addresses. This presentation can give an impression of inconsistency to users and can negatively affect your branding.

• It can be difficult to enforce consistent API rules and standards across all microservices. For example, one team may prefer to respond with XML and another may prefer JSON.

• You're reliant on individual teams to implement security in their microservice correctly. It's difficult to impose these requirements centrally.

• API Management acts as an intermediary. It forwards requests to the right microservice, wherever it's located, and returns responses to users. Users never see the different URIs where microservices are hosted.

• You can use API Management policies to enforce consistent rules on all microservices in the product. For example, you can transform all XML responses into JSON, if that is your preferred format.

• Policies also enable you to enforce consistent security requirements.

Remove technical information from API responses

• Remove technical information from API responses

• Companies that publish web APIs often need to carefully control the HTTP headers that their APIs return, preferably without rewriting the API source code.

• Response headers are metadata associated with HTTP responses that provide the detailed context of the response.

  • They can expose information about the Server and platform technology being used

• Mask URLs with a transformation policy

• API exposes details about the URL from which the API is being called from.

  • This information could allow a malicious user to attempt to access the census data by bypassing the API Management gateway and exposing a less secure endpoint.

  • As lead developer, you want to mask these URLs within the response body of the API.

  • It's best practice to secure the back-end API by configuring it to require a client certificate, and then configuring API Management to supply that certificate.

    • In this configuration, no one can call the back-end API directly and circumvent your API Management gateway because they don't have a certificate that's recognized by the back end.

The following transforms are available: