How To: Implementation of a CA API Gateway Custom Assertion

If you are using an API Gateway by CA Technologies you are maybe familiar with the concept of Assertions which are used to implement various specific tasks and processes. There is an abundance of existing Assertions and they cover most of usual scenarios.

But what happens if you cannot find a suitable Assertion for your use case? The answer is: developing your own Assertion – a Custom Assertion. It enables you, implementing your processes and integrating them in the CA API Gateway. This sounds very promising and we wrote down a short guide to support you on your journey to your first Custom Assertion.

Development Environment

Before we begin, we have to setup our development environment. To do so, we advise you to use the latest version of Eclipse, which you can download here .
Since the CA API Gateway is developed in JAVA, we have to develop the Assertions in JAVA as well – so a JAVA SDK is needed.
Furthermore, we need a plug-in for Eclipse that helps developing the Assertion. You can download the plug-in here . Please note, that the plug-in was developed by the CA Community, not by CA itself. If any troubleshooting is required hence ask the community. Still it is the best way to approach our goal – developing a Custom Assertion.
After having installed and configured Eclipse, you will have to embed the plug-in. To do so, you have to find the installation directory of Eclipse on your computer. Then, navigate to the folder “dropins” and store the plug-in’s JAR data („CA_APIM_CustomAssertionPlugin_X.jar“) in it. Now the plug-in is available in Eclipse.

Creating a project

Create a new „CA API Management Custom Assertion“ – Project (Menu>Project>New Project). Then you have to create the project’s most important meta data / features. A description of the fields is listed below: 

Project Name 

Put the name of the project in this field. It is only visible in the IDE. 

Assertion Package 

In this line you determine the Assertion’s package namespace. Please note that the prefix has to be „com.l7tech.custom.“! 

Assertion Code Name 

This is the name of the Assertion in the code. The classes which are created by the plug-in will be named after this. 

Assertion Display Name 

The name which is displayed on the API Gateway interface. 

Assertion Description 

The description which is displayed on the API Gateway interface. 

Assertion Category 

The category is Custom Assertion. For any further entries please check the official documentation by CA. 

Include Custom UI 

You can implement your own UI for the Assertion. If you wish to do so, confirm this field. Please consider, that the UI implementation is not part of this blog post. 

Click on „Finish“ to create the Assertion. Now you have successfully created your Custom Assertion! In the following we will take a closer look at the different classes.

Class description

Assertion Code Name_Assertion.java

This class is the link between your Assertion’s functionality and the Gateway. The input and output parameters are handled and published here. The class name depends on the meta parameter „Assertion Code Name“.

Variables

OUTPUT_STRING_VARIABLE_NAME
This is a context variable which can be set by the Assertion. Context variables are used as a return value of the Assertion. After processing data your Assertion can display the value of this variable. Within the Gateway you find it here: ${OUTPUT_STRING_VARIABLE_NAME}. It is important and obligatory to use a constant here, or else the variable will be treated as a parameter of the Assertion!

inputStringOne, inputStringTwo
The Assertion’s parameters. Depending on the use case, data types are changed, variables can be renamed, added or deleted here. It is important that getter and setter are implemented for every variable, otherwise they cannot be used within the ServiceInvocation-class.

Methods

public String getName()
This method passes the name of the Assertion to the Gateway.

public String[] getVariablesUsed()
In this method the variables are transmitted to the Gateway. At first, the method checks if the figures are initialized. If so – they are returned, if not – an empty array is returned. This method has to be revised according to the parameters.

public VariableMetada[] getVariableSet()
This method tells the Gateway which context variables are set by the Assertion.

Assertion Code Name_ServiceInvocation.java
This class is the core of your Assertion. For example, the application logic is implemented in the method “check Request” inside this class. The class contains a „logger“, which helps you creating log entries for your Assertion. The created log entries are available in the policy manager. For further information please check the official documentation of CA.

public CustomAssertionStatus checkRequest(final CustomPolicyContext customPolicyContext)
This method contains the business logic. It returns the state of the Assertion. Which can consist of one of the following figures:

– AUTH_FAILED

– FAILED

– FALSIFIED

– NONE

– UNAUTHORIZED

To reference your Assertion, you have to use the „CustomPolicyContext“, which is used as a parameter in the Assertion. „customPolicyContext.expandVariable(assertion.getInputStringOne())“ provides the figure for „inputStringOne“. Only figures, which own both getter and setter in Assertion.java can be referenced.
Furthermore, it is possible to get context variables from the Gateway. For example, „customPolicyContext.expandVariable(“${ssgnode.id}”)“ provides the Gateway’s Node-Id. For further context variables, please check the official documentation of CA.

Build

To build the JAR data of your Assertion runthe so-called „Ant-Build“as you can see in the screenshot below. (right-hand click „build.xml“ > „Run As“ > „1 Ant Build“). 

The JAR data is located in the „build“ folder of your project after that.

Congratulation! Now you are able to develop your own Custom Assertion.

Installation

After creating your Custom Assertion, you have to install it on your Gateway. There are different possibilities to do so:

Manually

This is a complex way to install the Assertion, but you do not need to get your Assertion signed by CA. Hence it is the best method for development issues.
Please note that it is possible to automate the process with the support of a script.

a. Build up SSH connection to the Gateway
b. Menu item 3: Privileged Shell
c. cd /home/ssgconfig
d. send data to Gateway via SCP (WinSCP or command line)
e. cp FILENAME /opt/SecureSpan/Gateway/runtime/modules/lib/
f. chown layer7:layer7 FILENAME
g. service ssg restart

Now we copy our Custom Assertion in the provided directory and change the access rights for user layer7. Then restart the API Gateway service. Your Assertion is now available in your policy manager.

Server Module File

Use this method for a rollout for your customers. Via the policy manager the server module file can be installed on the Gateway easily. The only limitation here is that the Assertion has to be signed by CA. Please contact the CA support team to get your Assertion signed.

SolutionKit

This one is another option to install your Custom Assertion. This issue is not part of this blog post. Please check the official documentation of CA for further information.

By the way:

With help of the APIIDA API Gateway Manager you can monitor and control your APIs in a very easy and comfortable way.