Securing and mediating APIs is a critical function for any API developer. The most frequent methods to secure an API is based on OAuth/OpenID Connect with (or without) Client Id/Secret, which are standard interfaces defined in an Open API specification. Mediation of an API is done within the API Gateway and is unique for each gateway implementation. API Connect provides API mediation via its API Assembly which includes out-of-the box policies to mediate API transactions, including programmatic extensibility via JavaScript (called GatewayScript) and XSLT. An API assembly is compromised of one or more policies, pipelined together to secure and mediate API payloads before sending the request to a backend service.
Modernizing business workloads can be a challenge since new modern security techniques don't integrate with traditional or legacy implementations. The DataPower API Gateway can help mediate between security protocols and bridge legacy applications with modern digital interfaces. In this article, you will explore several techniques to create and manage API policies.
Overview
The API Assembly supports User-Defined Policies that provide flexibility to package API Assembly policies into a single policy for reusability and governance. Furthermore, combined with a new GatewayScript API to invoke any DataPower rule object, it gives you the ability to access any function available within the DataPower Gateway!
In general, you will need to create User Defined Policies (UDP) for the API Gateway in one of the following situations:
- Reusable UDP: Package existing API Assembly policies into a single reusable policy that is shared across multiple developers or the enterprise. In this scenario, you don't need access to DataPower Gateway functionality exposed in the DataPower UI.
- UDP for Managed DataPower Objects: Create a UDP when a policy needs access to a Datapower object. For example, when you need to use an MQ queue manager or SQL Datasource in a GatewayScript or XSLT policy. In this scenario, you need access to the DataPower UI for creating the specific object(s).
- UDP for DataPower rule: Create a UDP that uses DataPower functionality such as AAA policy for functionality that is not available in the API Assembly (eg SAML Generate). In this scenario, you need access to the DataPower UI to create the DataPower rule that is invoked via the UDP policy.
The complexity of each type of policy increases (from #1 to #3), including your expected knowledge of DataPower Gateway functionality. In the next section, we will examine each type of UDP policy.
User-Defined Policies (UDP) Types
Basic UDPThe repository shows a sample DataPower configuration file and GatewayScript that you can customize based on your own requirements. The equivalent API Assembly actions used are the
Set-Variable and
GatewayScript policies. If you need other API assembly actions, you will need the equivalent DataPower configuration. More details on how to obtain this configuration will be provided later in the article.
You can easily reuse this UDP policy example, replace all instances of
udp-basic with the name of your policy. Furthermore, modify the GatewayScript file with your logic. If you open up
udp-basic-policy.cfg file, search for the string
$(local.parameter.credential) . This parameter is used to pass
runtime parameters that the API Developer enters when configuring your API Assembly. It can be used to drive dynamic behavior.
UDP For Managed DataPower ObjectsThe repository shows how to use a DataPower managed object from GatewayScript and XSLT policies. These objects must be created when you want to use functionality that is not available in the API assembly but exists within the DataPower Gateway.
You can write GatewayScript/XSLT to connect to an MQ queue manager and SQL Datasource, but the code requires access to an existing DataPower managed object. The configuration for these objects can be packaged within the Gateway Extension and the name needs to be used within the code. For example, in the snippet below,
IBM_Cloud_QM is the name of an existing DataPower MQ Queue Manager object, which must be defined when the code is executed.
var options = { target: 'dpmq://' + 'IBM_CLOUD_QM' + '/?'UDP for DataPower ruleThis repository shows how to create a UDP policy that invokes a Datapower rule. You will need to use GatewayScript and the
multistep module to call an existing DataPower processing rule. The creation of a DataPower multi-step rules is outside the scope of the article. The Datapower rule must also be packaged as DataPower configuration. You can find several examples of UDP policies in the repository for the token generation use case. Several GatewayScript files are packaged in the repository, you only need to focus on the
<udp-policy>-call-rule.js and
<udp-policy>-aaa-credential.js files. They will need to be modified to reflect the parameter names that you want to expose in the UDP p0licy.
Packaging
Several options exist for packing User-defined policies, using either
Gateway Extensions or individual UDP deployment. If your running on Kubernetes, you can package UDPs using the instructions
here. In this article, we will show how to package them via Gateway Extensions. This approach is easier since all your UDPs and any referenced files exist within the API Manager so that deployment across a cluster of API Gateways is managed whether your on Kubernetes or OVA. The API Manager includes the Gateway Extension CLI to store the Gateway Extension within the API Manager so you can perform managed deployments into the gateway cluster.
When deploying a Gateway Extension, consider the following:
- A single Gateway extension is deployed to a Gateway cluster. Artifacts are packaged into a ZIP file containing .cfg files, together with any dependent files that are referenced from the CFG file.
- All files must be at the root of the ZIP file. The CFG files are processed in alphanumeric order by file name.
- ZIP files are uploaded to the file system:
local:///filestores/extensions/gateway-extension/ so any file references within UDP must be adjusted accordingly.
DataPower configuration packaged into a UDP must be in the form of CLI commands, for both managed Datapower objects or DataPower rules. The DataPower UI provides the ability to import / export ZIP files but support for CFG is not available yet. My recommendation would be to copy the exact DataPower CLI commands from the DataPower file system (
config:///<domain>.cfg. You can find the appropriate commands based on the naming convention. Place the CLI commands into the appropriate file, following conventions in the provided examples.
Once the Gateway extensions are deployed, they should appear in the API Assembly editor and you can use them like any out-of-the box policy in the API designer.
Summary
In this article, you learned how to create User-defined policies that allow you to extend the behavior of the API Gateway, enabling reuse and accelerating API development. Three types of UDPs are available, based on your requirements, ranging from simple reusable API assembly policies to leveraging DataPower managed objects and rules. Use Gateway extensions to package your UDPs and deploy them across a Gateway cluster, also making them available within the API designer.
#APIConnect#APIConnectv.2018.1