Updating the HTTPS Connector resource manager by using the administration REST API

You can use the IBM® App Connect Enterprise administration REST API to query and update resource managers that are available to the integration server. This topic describes how to use the administration REST API to update the HTTPS Connector integration server resource manager with particular focus on reloading the inbound security certificate.

Before you begin

Read the following topic:

About this task

When receiving secured inbound connections over HTTPS, integration servers use the HTTPS Connector resource manager. You can query and update the HTTPS Connector resource manager by using the App Connect Enterprise administration REST API. You do not have to restart the integration server for such updates to take effect.

There are a number of situations that might require updates to the properties of the HTTPS Connector resource manager in an integration server. You can dynamically update the properties in question by using the PATCH verb in the administration REST API. Updates that are made by using the PATCH verb are persisted in the overrides sub-directory of the integration server working directory meaning that, if the integration server is restarted, the updates are not lost.

This topic describes:

Querying the available resource managers of an integration server

Procedure

Use one of the following REST API methods to query the available resource managers of an integration server.
  • For an independent integration server:
    GET http://hostname:port/apiv2/resource-managers
  • For a managed integration server:
    GET http://hostname:port/apiv2/servers/{server}/resource-managers

Querying the properties of the HTTPS Connector resource manager

Procedure

Use one of the following REST API methods to query the properties of the HTTPS Connector resource manager.
  • For an independent integration server:
    GET http://hostname:port/apiv2/resource-managers/https-connector
    For example, use the curl command:
    curl -X GET http://hostname:port/apiv2/resource-managers/https-connector
    A response similar to the following is returned:
    {"hasChildren":false,"name":"https-connector","type":"resourceManager","uri":"/apiv2/resource-managers/https-connector",
"properties":{"AutoRespondToHTTPHEADRequests":false,"CORSAllowCredentials":false,"CORSAllowHeaders":"Accept,Accept-Language,
Content-Language,Content-Type","CORSAllowMethods":"GET,HEAD,POST,PUT,PATCH,DELETE,OPTIONS","CORSAllowOrigins":"*",
"CORSEnabled":false,"CORSExposeHeaders":"Content-Type","CORSMaxAge":-1,"CipherSpec":"!RC4+RSA:HIGH:+MEDIUM:+LOW",
"ConnBacklog":100,"EnableLookups":true,"EnableTLSTrace":false,"IWATimeout":300,"IntegratedWindowsAuthentication":"",
"KeyAlias":"","KeyPassword":"********","KeystoreFile":"","KeystorePassword":"********","KeystoreType":"JKS",
"ListenerAddress":"0.0.0.0","ListenerPort":7843,"ListenerThreads":-1,"MaxConnections":-1,"MaxKeepAliveRequests":-1,
"MaxPostSize":-1,"QueueCapacity":1000,"ReqClientAuth":false,"ServerName":"","TLSCertVerifyDepth":100,"TLSContextTimeout":300,
"TLSProtocols":"","TimeoutSweepInterval":20,"TruststoreFile":"","TruststorePassword":"********","TruststoreType":"JKS",
"name":"HTTPSConnector","type":"Policy"},"descriptiveProperties":{"className":"HTTPSConnector","isDynamic":"true",
"policyType":"HTTPSConnector"},"active":{"ListenerPort":-1,"serverRestartRequired":false},"actions":{"available":{"refresh-tls-config":
"/apiv2/resource-managers/https-connector/refresh-tls-config"}},"children":{},"links":[]}
  • For a managed integration server:
    GET http://hostname:port/apiv2/servers/{server}/resource-managers/https-connector
    For example, use the curl command:
    curl -X GET http://hostname:port/apiv2/servers/{server}/resource-managers/https-connector

Dynamically updating the properties of the HTTPS Connector resource manager

Procedure

Use one of the following REST API methods to dynamically update the properties of the HTTPS Connector resource manager.
Being able to dynamically update these properties, in particular KeystoreFile is useful in the situation where you are using certificate authorities that refresh their certificates on a frequent basis but you do not want to restart the integration server whenever the refresh occurs.

Updates take effect on the first inbound connection following the update; preexisting connections retain the original configuration. You do not have to restart the integration server for the changes to take effect.

You can update the following HTTPS Connector resource manager properties:
  • KeyAlias
  • KeystoreFile - you can specify the path to an updated inbound server certificate without the need to restart the integration server for the certificate to be applied on subsequent inbound connections.
  • KeystorePassword
  • KeystoreType
  • TruststoreFile
  • TruststorePassword
  • TruststoreType
For more information about these parameters, see Integration server HTTP listener parameters (SOAP and HTTP nodes).
  • For example, to update the KeyAlias, KeystoreFile, KeystorePassword, and KeystoreType properties for the HTTPS Connector resource manager for an independent integration server, use the following curl command with the PATCH verb:
    curl -X PATCH -H "Content-Type: application/json" http://hostname:port/apiv2/resource-managers/https-connector 
-d "{\"properties\": {\"KeyAlias\":\"server1cert\",\"KeystoreFile\": \"C:\\temp\\myserver_keystore.p12\",\
"KeystorePassword\": \"server::keystorePass\",\"KeystoreType\": \"p12\"}}"
  • For a managed integration server, to update the same properties for the HTTPS Connector resource manager for a managed integration server, use the following curl command with the PATCH verb:
    curl -X PATCH -H "Content-Type: application/json" http://hostname:port/apiv2/servers/{server}/resource-managers/https-connector 
-d "{\"properties\": {\"KeyAlias\":\"server1cert\",\"KeystoreFile\": \"C:\\temp\\myserver_keystore.p12\",\"KeystorePassword\": \
"server::keystorePass\",\"KeystoreType\": \"p12\"}}"
If the command is successful, an HTTP status code 204 is returned. You can see the updated values in theoverrides sub-directory of the integration server working directory.

Dynamically loading a new server certificate by reusing the same keystore file

About this task

You can reuse the same keystore file but with a different value for the server security certificate to refresh the server certificate to be used by the integration server without having to restart the integration server. Instead of updating the server certificate by using the PATCH verb in the REST API, as described in Dynamically updating the properties of the HTTPS Connector resource manager, you must use the POST method to load a new server certificate that you have defined in a certificate file with the same name as one that you have previously used.

Procedure

Use the following commands to refresh the integration server TLS configuration, including the updated server certificate value in the reused certificate file.
Updates take effect on the first inbound connection following the update. You do not have to restart the integration server for the changes to take effect.
  • For example, to ensure the use of an updated server certificate specified in a reused certificate file for an independent integration server, use the following curl command:
    curl -X POST http://hostname:port/apiv2/resource-managers/https-connector/refresh-tls-config
  • For a managed integration server:
    curl -X POST http://hostname:port/apiv2/servers/{server}/resource-managers/https-connector/refresh-tls-config
If the command is successful, an HTTP status code 200 is returned.