Contribute in GitHub:
Open doc issue|Edit online
Certificate Management
IBM® Application Gateway (IAG) handles all configuration data as text, including certificates. Certificate data must always be provided to IAG as ASCII PEM-encoded data.
Working with Private Keys and Certificates
When handling private keys, IAG expects PEM-encoded data including:
- a private key
- a certificate signed with the private key
- the signer certificate or signer certificate chain (if required)
Note that the signer certificate may not be required if the certificate was issued by a recognised certificate authority, or if a self-signed certificate is being used.
server:
ssl:
front_end:
certificate:
- "@ca.pem"
- "@ca-chain.pem"
- "@server.key"
Private keys and certificates are used by IAG in the following locations:
| Location | Purpose |
|---|---|
| server/ssl/front_end/certificate | The application gateway front end. This is the default certificate which is presented by the HTTPS interface when clients connect to IAG. If this parameter is not specified, the application gateway will generate a self-signed certificate while bootstrapping. |
| server/ssl/front_end/sni[]/certificate | The application gateway front end for a particular host when the client uses Server Name Indication (SNI) during the TLS handshake. The usage of SNI is optional and the default certificate will be used if SNI is not configured. |
| resource_servers[]/mutual_auth/certificate_auth/certificate | Used by the application gateway to authenticate to a resource server when that resource server requires certificate based mutual authentication. |
| resource_servers[]/identity_headers/jwt/certificate | Used by the application gateway to sign JWTs which are presented to resource servers. |
Generating a Self-Signed Private Key and Certificate
A private key and self-signed certificate can be generated using OpenSSL:
openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout key.pem \
-out cert.pem -subj /C=us/O=ibm/CN=www.iagdemo.com
The resulting private key and certificate are written to separate PEM-encoded files, which can be provided to IAG:
server:
ssl:
front_end:
certificate:
- "@cert.pem"
- "@key.pem"
Using an Existing Private Key and Certificate from a PKCS12 key archive
To use an existing certificate and key from a PKCS12 key archive, the contents must first be extracted to a PEM encoded certificate file. For example:
openssl pkcs12 -in "test-iag.p12" -out "test-iag.pem" -nodes
Note that the source PKCS12 key archive is typically password protected and this operation will produce an PEM-encoded file which is not protected.
The resulting PEM-encoded file can then be provided to IAG:
server:
ssl:
front_end:
certificate: "@test-iag.pem"
Trusting Certificates
If a resource server presents a certificate which was not signed by a known certificate authority, the certificate of the signer must be supplied to IAG. IAG does not trust certificates signed by unknown certificate authorities and will not establish TLS connections to servers presenting certificates which are not trusted.
When handling signer certificate data, IAG expects PEM-encoded data containing:
- the signer certificate or signer certificate chain.
Note that a signer certificate may not be required if the remote server certificate was issued by a recognised certificate authority.
To provide a signer certificate and chain to IAG, ensure that the certificate data is in PEM-encoded format and provide them both.
If the required certificate data is just a single certificate, ensure that it is PEM-encoded and provide it as-is.
resource_servers:
- path: /iagExample
connection_type: ssl
...
servers:
- host: exampleHost.ibm.com
port: 443
...
ssl:
certificate:
- "@resource-ca.pem"
- "@resource-ca-chain.pem"
Signer certificates are used in IAG configuration for:
| Location | Purpose |
|---|---|
| resource_servers[]/servers[]/ssl/certificate | A signer certificate (if required) that the application gateway can use to assert that it should trust the certificate presented by the resource server. |
Retrieving Certificate Data from Remote Servers
If you do not have the certificate or certificate chain for a remote server, openssl can be used to establish a TLS connection to the server and print the certificates presented by the server.
The following command can be used to retrieve the certificate or certificate chain from a remote server.
openssl s_client -showcerts -host "$HOSTNAME" -port "$PORT" < /dev/null |
sed -ne '/-----BEGIN CERTIFICATE-----/,/-----END CERTIFICATE-----/p'
> resource_server.pem
The created file 'resource_server.pem' will contain the root certificate from the server in PEM-encoded format. Providing this root certificate is the CA certificate it can then be used with IAG.
Note that manual inspection should be performed on the certificate data retrieved using this method to ensure it is correct.