This time I’ll write a tutorial on how to create IBM APIC Custom Gateway Extension in IBM API Connect v2018 using DataPower API gateway. IBM API Connect has provided quite a few features and policies for us to use. But these are not adequate when building enterprise solutions. IBM API Connect provides us a framework using which we can extend the functionalities of APIC. We don’t have to always depend on IBM to deliver those expected features.
When I went through the APIC knowledge center articles and example of gateway extension, I actually couldn’t relate as to why someone would use gateway extension to modify an API or Plan definition. Instead one should create a new version of API and Product. If any of you reading this article has an explanation for that, please do comment. It will be great to understand the perspective.
Nevertheless, I’ll explain the extension creation with an example that I have used and feel that it is a good example to connect with.
Just a point of note, if you are beginner, please go through my other blogs to learn how to install and some interesting topic of API development:
- https://iteritory.com/install-ibm-api-connect-lte-in-local-windows-system/
- https://iteritory.com/ibm-api-connect-tutorial-part-1-develop-your-first-api/
- https://iteritory.com/ibm-api-connect-tutorial-part-2-ibm-apic-map-policy-with-example/
Before proceeding, I must express my gratitude to Mr. Usame Goksun for teaching me this one. In this tutorial, I am articulating the knowledge I gathered from him.
Use Case
We will learn how to create a new Crypto Key, Crypto Certificate object and make these objects available to APIC gateway using custom gateway extension.
Most of you must have already either worked with JWT or are aware of it. In JWT, the third segment of the token is the signature. You can generate the signature in different ways (eg. using symmetric or asymmetric cryptography). IBM APIC supplies JWT generation and validation policy. However, if your goal is to to create JWT token with a signature using private key or validate a token with a public key (Asymmetric cryptography), there is no straight forward way.
If you notice the yellow highlighted segment in the following GUI snippet, there is a field to provide the crypto cert object (in JWT validate policy). But how do we create those objects? We can’t just create the crypto objects manually using the DataPower GUI. IBM does not recommend to manually create objects in API Connect domain like this. This is where we’ll use custom extension to create these objects.
So, let’s start learning how to create IBM APIC Custom Gateway Extension in IBM API Connect v2018 using DataPower API gateway
Create the CLI script for Crypto Cert object
Typically, we write these gateway extensions by using a bunch of CLI commands that are provided by DataPower. Now, most of us are unsure of the syntax and how to use such CLI commands in Datapower. So, let’s learn an easy hack.
- Let’s keep the certificate handy.
- We’ll login to DataPower default domain and upload the certificate in sharedcert folder.
- Let’s switch to any domain other than the domain reserved from API Connect.
- Now, we will create a Crypto Certificate object (I am creating with name cryptocert_poc) and refer to the certificate file that we just uploaded in the sharedcert folder. Save the configuration.
- Now, let’s go to File Management and expand the config folder. You’ll find a file with the name of domain itself. Let’s open the file.
- In this .cfg file, let’s search for the object that we just created. Basically, this file contains all the CLIs of the objects created in Datapower from GUI.
- We’ll now copy the commands that are used to create the crypto object. Our CLI script will be as follows:
|
1 2 3 4 |
top; configure terminal; crypto certificate "cryptocert_poc" "sharedcert:///iteritory.cer" exit |
- Now, switch to the APIC domain in Datapower and head to File Management. Expand the temporary\config folder.
- There will be quite a few files with names starting with a number. Note the highest number. For example, in the below snippet, you can see the highest number is 30.
- We’ll now save the CLI script (that we copied above) with a number greater than the number present above. For example, I’ll save the script with a name 40.gw_ext_cryptocert_poc.cfg
Create the CLI script for Crypto Key object
- Let’s keep the crypto key file handy.
- We’ll now login to DataPower default domain and upload the key in sharedcert folder.
- Let’s now switch to any domain other than the domain reserved from API Connect.
- We will now create a Crypto Key object (I am creating with name cryptokey_poc) and refer to the key file that is just uploaded in the sharedcert folder. Save the configuration.
- Now, let’s go to File Management and expand the config folder. You’ll find a file with the name of domain itself. Open the file. We’ll now copy the commands that are used to create the crypto key object. Our CLI script will be as follows:
|
1 2 3 4 5 6 7 |
top; configure terminal; password-alias "pma_cryptokey_poc" password-encrypted "j0MIGu/cbO3a0HZ/JpCqUhDqeZG7smB+" exit crypto key "cryptokey_poc" "sharedcert:///keystore.p12" password-alias "pma_cryptokey_poc" exit |
- Let’s save the CLI script with a number greater than the number used above. For example, I’ll save the crypto key script with a name 50.gw_ext_cryptokey_poc.cfg
- We’ll create a folder C:\apigwext save both the .cfg files in this folder.
Package the cfg files
Select these two files and add to a .zip file
Create the IBM APIC Gateway Extension
- Now, open the command prompt and execute following command to login to API management using admin user.
|
1 |
apic login --server 127.0.0.1:2000 --username admin --password 7iron-hide --realm admin/default-idp-1 |
- Thereafter, execute the following command to create the gateway extension
|
1 |
apic gateway-extensions:create C:\apigwext\apigwext.zip --scope org --org admin --gateway-service datapower-api-gateway --availability-zone availability-zone-default --server 127.0.0.1:2000 |
- Upon successful execution, it will give an output like:
|
1 |
gateway-extension https://127.0.0.1:2000/api/orgs/42535da0-4c43-45cc-bed4-d190f4789235/availability-zones/4f8893e7-569b-4cb9-976a-9776d4abca1d/gateway-services/d35b86b5-c1e3-4005-a155-c4a2989d9ffc/gateway-extension |
- We can also run the following command and check the output to confirm that the gateway extension is actually created
|
1 2 3 4 5 6 7 8 9 10 11 12 13 |
apic gateway-extensions:get --scope org -o admin --gateway-service datapower-api-gateway --availability-zone availability-zone-default --server 127.0.0.1:2000 --output - type: gateway_extension api_version: 2.0.0 name: gateway-extension gateway_service_url: >- https://127.0.0.1:2000/api/orgs/42535da0-4c43-45cc-bed4-d190f4789235/availability-zones/4f8893e7-569b-4cb9-976a-9776d4abca1d/gateway-services/d35b86b5-c1e3-4005-a155-c4a2989d9ffc scope: org created_at: '2020-12-25T19:17:42.291Z' updated_at: '2020-12-25T19:17:42.291Z' org_url: 'https://127.0.0.1:2000/api/orgs/42535da0-4c43-45cc-bed4-d190f4789235' url: >- https://127.0.0.1:2000/api/orgs/42535da0-4c43-45cc-bed4-d190f4789235/availability-zones/4f8893e7-569b-4cb9-976a-9776d4abca1d/gateway-services/d35b86b5-c1e3-4005-a155-c4a2989d9ffc/gateway-extension |
- Apply the extension to the gateway server by restarting the API Connect gateway service object; complete the following steps on each Gateway server in the Gateway service:
- Log in to the DataPower; switch to the domain reserved for API Connect
- Search for API Connect Gateway Service
- Set the Administrative State to disabled.
- Apply the changes.
- Set the Administrative State to enabled.
- Apply the changes.
Verify the created objects
Now, let’s verify that what is the actual outcome of the tedious job we just did!
- Log in to the DataPower; switch to the domain reserved for API Connect
- Search for Crypto Certificate and verify that our intended crypto certificate is created
- Similarly, search for Crypto Key and Password Alias and verify that needed objects are created.
Conclusion
In this tutorial, we learnt how to create the custom gateway extensions in IBM APIC Custom Gateway Extension in IBM API Connect v2018 using DataPower API gateway. In the future tutorials, we will use these objects and develop a POC to generate JWT and validate JWT
