Best Practices from Oracle Development's A‑Team

API Gateway SSL configuration in Production

Gaurav Gupta
Principal Solutions Architect (A-team)


This blog provides steps to configure SSL certificate in Oracle API Gateway node's trust store. It becomes necessary when API gateway in installed in "production" mode. Without SSL certificate you won't able to deploy an API to gateway node, because in production mode gateway must communicate with APIP management tier over SSL. Another use-case is when backend service is SSL enabled.

  1. We will discuss both the scenarios in this blog.
  2. 1. Configure certificate in gateway node for SSL based communication with APIP management tier
    2. Configure certificate in gateway node when API is consuming SSL enabled backend service.

Scenario#1 : When gateway is installed in Production mode (gatewayExecutionMode="Production"), it communicates with APIP management tier over SSL.

There are certain configurations need to be done in gateway for successful SSL Handshake with management tier. Before we jump into the gateway configuration, let's see types of certificates configured in management tier.

Mostly there are 2 types of Digital certificates configured in management tier.

(i) WebLogic Self-signed certificate (Provided by default as WebLogic "demo" certificate. Not recommended for Production environment)
(ii) Custom CA Signed certificate (It is recommended that you should replace WebLogic demo cert with CA signed cert for production usage) (To learn how to configure CA singed certificate you can refer A-team blog - http://www.ateam-oracle.com/api-platform-custom-host-name-and-certificate/)

Now, Let's see kind of problems you may face in absence of certificate.


  • Once GW is installed & registered successfully to management tier, If you try to deploy an API on gateway it won't get deployed and will remain in "waiting" state. If you check apics.log file in gateway node you are likely to see SSLHandshakeException as shown in snippet below. (apics.log file location - <GatewayInstallDirectory>/domain/gateway1/apics/logs)

    [08-08 04:43:25:ERROR oracle.apiplatform.gateway.controller.rest.ManagementRestMethods] Failed to GET from https ://<API mgmt tier hostname>:443/apiplatform/gatewaymanager/v1/gateways/101/newdeployments
    javax.ws.rs.ProcessingException: javax.net.ssl.SSLHandshakeException: General SSLEngine problem
    at org.glassfish.jersey.client.internal.HttpUrlConnector.apply(HttpUrlConnector.java:287)
    at org.glassfish.jersey.client.ClientRuntime.invoke(ClientRuntime.java:255)
    at org.glassfish.jersey.client.JerseyInvocation$2.call(JerseyInvocation.java:700)

  • This error is because gateway node is unable to poll the management tier to retrieve latest APIs, artifacts, entities etc, for deployment. Because in Production mode gateway is forced to communicate with management tier over SSL. That means gateway needs to perform following checks.
      (i) Check if valid certificate is available
      (ii) Verify hostname in certificate matches with management tier hostname

    • To get rid of above issue we need to import certificate from APIP management tier to Gateway's JDK key store cacerts. (<<JDKPATH>>/jre/lib/security/cacerts). This can be done using SSL Import utility available at - https://docs.oracle.com/en/cloud/paas/api-platform-cloud/apfad/using-ssl-certificate-import-utility.html.
    • As mentioned in the document, Once you download and run the utility it asks for source server & target truststore for certificate. Then it automatically retrieves necessary certificates from the server in proper format. (You can also use Java keytool command. However SSLImportUtility is built for this requirement and encapsulates internal complexity).
    • Once certificate is imported successfully in Java keystore, We want gateway to point to the Java trust store. For that Login to Gateway's WebLogic console. Go to managedServer1->keystore.
      • Check value of "keystores".By default it is "Demo Identity and Demo Trust". Change it to "custom Identity and Java Standard Trust". Save it.
      • Verify path in "Java Standard Trust keystore" pointing to the cacerts where you had imported the certificate.
      • Save & Activate Changes. No need to restart Gateway node.
  • These changes should get your gateway node working.
  • Note, I have suggested to import certificate in JDK truststore and not in the default WebLogic truststore. Because there is an analytics component in gateway that works as independent java process, Hence it uses JDK's truststore. If we import cert only in WebLogic keystore we will get APIs working (deploy, execute) but won't get to see analytics on management console. Because analytics component won't be able to communicate with management tier in absense of certificate in JDK truststore.


What if customer doesn't have CA signed certificate configured in APIP management tier?

  • Above solution will work with CA signed certificate. However if customer doesn't have CA signed certificate configured for APIP management tier, and wants to use self-signed certificate then there is a catch.
  • In case of self-signed certificate even you've imported a certificate in truststore, you are likely to get Hostname verification error as shown in sample below.

    <Aug 9, 2018 5:20:40,037 PM GMT> <Warning> <Security> <BEA-090504> <Certificate chain received from oc-<OTD_IP_Address>.compute.oraclecloud.com -<OTD_IP_Address>failed hostname verification check. Certificate contained apics-lb-1 but check expected oc--<OTD_IP_Address>.compute.oraclecloud.com>
    Note, this error is different from previous SSL handshake exception. Because as mentioned earlier, There are 2 steps performed by gateway for SSL based communication. Certificate check & Hostname verification.

  • In case of Self singed cert we are likely to hit hostname verification exception because unlike CA signed cert, there is no hostname specified in self-signed certificate.

  • In this case recommended solution is to install gateway in "Development" mode. Because WebLogic demo self-signed certificate is not considered as secure and it is meant for Development environment only. So with self-signed certificate, we are really not taking advantage of security parameters getting configured with Production mode.
  • It is highly recommended, that you should not try to change gateway node configurations manually to fix hostname verification error.

Scenario#2 : Configure certificate in gateway node when API is consuming SSL enabled back-end service.

Here process is exactly similar as above scenario described in #1. We just need to import certificate used by back-end service to API gateway node. We can use same SSLImportUtility to import certificate, as discussed above.


Appendix - Gateway Lockdown

Since we are discussing security configuration for prod environment of gateway node. it reminds me another recommendation to Lockdown gateway. While it is a different topic from SSL but worth mentioning in context of security.

  • Gateway has certain internal REST APIs which we don't want to be invoked from outside. These APIs are meant for internal consumption of Gateway or certain Admin activities. So these APIs should be locked down. Lockdown will restrict access to the internal endpoints to just the local servers in the domain.
    • Example lockdown action - ./APIGateway -f gateway-props.json -a lockdown
    • (Please refer documentation to understand properties needs to be set in gateway-props.json before running lockdown. Else it may break operation of gateway controller)
  • These internal APIs endpoints have /prm_pm_rest and /apiplatform as context root. So make sure you don't use these context root while creating APIs in API management console.
  • Here is document link for more information on lockdown - https://docs.oracle.com/en/cloud/paas/api-platform-cloud/apfad/configuring-gateway-node-domains.html#GUID-09A8BCD4-AE91-40E1-A375-49FA1D5189ED

Be the first to comment

Comments ( 0 )
Please enter your name.Please provide a valid email address.Please enter a comment.CAPTCHA challenge response provided was incorrect. Please try again.Captcha

Recent Content