RESTful APIs are often exposed over the open Internet for consumption. API providers need a mechanism to prevent unauthorized access to the API. One approach is to provision consumers with API keys. Those keys can be used as authentication tokens.
CentraSite API Management Solutions automatically generates API keys when a consumer request for consumption of that API. It enables API providers to view, approve and set expiration for API keys. By applying a policy workflow, you can enforce verification of API keys at runtime. This ensures that no consumer can access a protected API without a valid key.
API keys are verified at runtime to ensure that:
The API key presented is valid and has not been expired.
The API key presented is approved to consume an API that includes the URI in the request.
Note:
Throughout this section, the term "Virtual Alias" is also
referred to as "Virtual API" or simply" API". The
name can be used interchangeably.
This section provides information about consuming APIs that are published in the webMethods Mediator. If you are using a different kind of PEP, refer to its documentation for publishing procedures and information.
Consumption refers to the process you use to
Consumer initiates the consumption by selecting the API that is to be consumed and specifies the authentication credentials by which he is to be identified.
CentraSite generates the API key for consumption of the API (the specific key generation steps depend on the configuration settings defined by the Provider of that particular API). Later, CentraSite prepares the API for publishing and invokes the deployer service on the Mediator. The generated API key is submitted as input to this API.
The deployer service publishes the API in the Mediator.
If the publishing is successful, the deployer service returns a success message and data that is pertinent to the published API. (This includes the Access URL and the API key that are required to consume this API). If the publishing is unsuccessful, the deployer service returns a failure message.
Consumer accesses the URL for API consumption, sends the API key as integral part of the HTTP request header or as a query string, and upon validation of the API key consumes the API.
If the consumption is successful, the consumer uses the API. If the consumption is unsuccessful for some reasons of authentication, a 500 fault is returned.
To determine the consumer from which an API consumption request was submitted, an API must have the policy enforcement rule defined with at least one Evaluate action. This action extracts a specified evaluator from an incoming request and locates the consumer defined by that identifier.
For example, if you configure the "Evaluate IP Address" action to evaluate consumers by IP address, Mediator extracts the IP address from a request's HTTP header and searches its list of consumers for the consumer that is defined by that IP address.
You can configure the Evaluate actions to evaluate consumers based on the following information in a request message.
Evaluator | Description |
---|---|
IP Address | The IP address from which the request originated. |
Host Name | The name of the host machine from which the request originated. |
HTTP Authentication Token | The user ID submitted by the requestor when it was asked to provide basic HTTP credentials (username and password). |
WS-Security Authentication Token | The WSS username token supplied in the header of the SOAP request that the consumer submitted to the API. |
XPath | |
Consumer Certificate | The X.509 certificate supplied in the header of the SOAP request that the consumer submitted to the API. |
REST services rely on HTTP methods like GET, POST, PUT and DELETE to make request to an API provider, so the API keys are closely tied to these HTTP methods, where they are sent as part of these HTTP method requests.
CentraSite allows you to set API keys as part of the HTTP header or as the query component of an API request.
Important:
In the case where a consumer is sending a request with both
credentials (HTTP header) and (query string), the HTTP header take precedence
over the query string when the Mediator is determining which credentials it
should use for the
consumption.
The API keys are passed as the HTTP header component of an API consumption request. The HTTP header corresponds to an array of header names to include for that particular API consumption.
The following example demonstrates a typical HTTP request with API keys that form the header value of the API Access URL.
x-CentraSite-APIKey:a4b5d569-2450-11e3-b3fc-b5a70ab4288a
The API keys are passed as the query component of an API consumption request.
The following example demonstrates a typical HTTP GET request with API keys that form a query string of the API Access URL.
http://localhost:5555/ws/RestAPI?APIKey=a4b5d569-2450-11e3-b3fc-b5a70ab4288a
Notice that the API keys are added to the path after a “?”, and specified as key-value pair.
When you request an API for consumption using the Access URL and the generated API key, CentraSite automatically validates the APIs run-time actions to ensure that any Evaluate action that appears in the policy enforcement rule of an API is validated with the consumer requesting for that API.
If the API consumption encounters a problem due to one or more of the following reasons, a 500 SOAP fault is returned.
If the API key value in the HTTP header or the query string is authenticated as invalid.
The sample message looks like this:
The request is authenticated as invalid.
If the HTTP header is not present in the request.
The sample message looks like this:
A required header is missing in the request.
If the API key value in the HTTP header is expired.
The sample message looks like this:
The API key has expired.