Copyright © Cloud Software Group, Inc. All Rights Reserved

Mutual SSL Authentication

When the client sends a request using HTTPs transport, TIBCO API Exchange Gateway supports the authentication of the client based on the digital certificates. This is known as two-way (mutual) SSL authentication. Mutual SSL authentication is also referred as client authentication, as with client authentication the client presents its certificate to the server after the server authenticates itself to the client.

TIBCO API Exchange Gateway uses X.509 digital certificates for mutual SSL authentication and to authorize client requests. In this case, authorization of the request is based on the trusted identity in the gateway processing pipeline. The trusted identity is represented by the digital certificate's X.509 subject distinguished name or the certificate's serial number.

TIBCO API Exchange Gateway uses the Apache HTTP server to terminate the incoming HTTP and transports. The actual mutual SSL authentication is handled in the Apache module of the TIBCO API Exchange Gateway. The Apache module authenticates each client request and extracts credentials from the X.509 certificate. The facade layer of the gateway uses those credentials to authorize the request before forwarding it to the Core Engine.

The following are the high-level steps for mutual SSL authentication:

Generate Keys and Certificates

See Generate Private Keys And Public Certificates with OpenSSL to generate the private keys and public certificates.

Configure SSL on Apache HTTP Server

Enabling SSL on the Apache HTTP server provides a secure and encrypted connection to the client as the Apache HTTP sever authenticates itself to the client.

Enabling the SSL communication requires the mod_ssl Apache module. The mod_ssl Apache module provides strong encryption using the secure sockets layer (SSL) and transport layer security (TLS) protocols for the HTTP communication between a client and the Apache HTTP server. Using SSL/TLS, a private connection between the Apache HTTP server and the client is established. Data integrity is ensured and the client is able to authenticate the server. In this case, the Apache HTTP server sends its digital certificate to the client before any request is processed.

The mod_ssl Apache module on the server guarantees to the client that the server is an uniquely correct end point for the communication.The client uses the public key contained in the digital certificate to encrypt the communication between the client and the server. The mod_ssl Apache module does not implement the SSL/TSL protocols itself, but it acts as an interface between the Apache module and the OpenSSL library.

For the configuration steps, see Configuring Mutual SSL on Apache HTTP Server.

Configure Client Authentication with Digital Certificates on Apache HTTP Server

The Apache HTTP server and clients can communicate over an encrypted connection using the SSL communication. This reduces the risk of exposing sensitive content in plain text. The secured communication using an encrypted connection ensures that the server always identifies itself to its clients. This guarantees that the server is the uniquely correct end point for the communication. However, if you want to authorize the service requests in TIBCO API Exchange Gateway, the clients must authenticate themselves to the Apache HTTP server using its own client certificates.

The client authentication can be configured on the Apache HTTP server by setting the following Apache directives in the virtual host configuration for the SSL virtual server instance:

•	SSLVerifyClient

The SSLVerifyClient directive defines the verification type. The possible values are as follows:

−	none: indicates that no client certificate is required at all.

−	optional: indicates that the client may present a valid certificate.

−	require:indicates that the client has to present a valid certificate.

The require value is used to ensure that the Apache HTTP server authenticates every client request before it forwards it to TIBCO API Exchange Gateway.

−	optional_no_ca: indicates that the client may present a valid certificate but does not have to be successfully verified.

•	SSLVerifyDepth

The SSLVerifyDepth directive specifies the depth of the certificate issuer chains verification. If the server does not find a trusted Certificate Authority (CA) within this depth, it declares the certificate invalid. The depth actually is the maximum number of intermediate certificate issuers, that is, the maximum number of CA certificates that is followed while verifying the client certificate. For example, Depth 0 (zero) means that all clients must present certificates that are self-signed and present in the server's collection of trusted certificates. Depth 1 means that client certificates may be either self-signed (as previously mentioned), or signed by a trusted CA. The default value is 1.

•	SSLCACertificatePath

The SSLCACertificatePath directive specifies the path to a directory containing certificate authority’s digital certificate files. Each digital certificate has a separate file. However, when you use this SSLCACertificatePath directive, the Apache HTTP server expects that each file be named with the hash of the CA certificate that is in it, followed by a period and a sequence number that starts at 0 and gets incremented for each file. The Apache server expects this for efficiency reasons. When you have a large number of CA certificates, it becomes inefficient to open and read every file in the directory every time it needs to find a specific certificate.

•	SSLCACertificateFile

The SSLCACertificateFile directive specifies the name and location of a single certificate file that contains all CA certificates.

Configuring the SSLCACertificateFile directive is easy. As the number of trusted certificate authorities increases, it can be difficult or error prone to add, replace, or remove CA certificates in this file. When the number of trusted certificate authorities is large, using the SSLCACertificatePath directive is recommended.

See Configuring Client Authentication with Digital Certificates on Apache HTTP Server for configuration steps.

Configure Client Certificate Identification Details On Apache HTTP Server

After setting up the client authentication configuration on the Apache HTTP server, configure the identity details of the authenticated client on the Apache HTTP server. The identity details of the authenticated client can be forwarded as custom HTTP headers to the Core Engine. The Core Engine matches the client identification details from the HTTP headers with the identification details configured on the Config UI.

By default, the Apache HTTP server does not forward the authenticated client identity to TIBCO API Exchange Gateway. Therefore, all requests that TIBCO API Exchange Gateway receives through this channel are identified as being sent by the anonymous user.

TIBCO API Exchange Gateway retrieves the client’s identity from the two custom HTTP header fields CAissuer and SerialNumber. The CAissuer field contains the distinguished name of the certificate authority that issued the client certificate. The distinguished name provides the unique identification of that certificate authority. The SerialNumber HTTP header contains the unique identification of the client in the context of a TIBCO API Exchange Gateway partner. This could either be the client certificate’s serial number, or the certificate’s subject distinguished name.

When TIBCO API Exchange Gateway receives a request that includes these two HTTP header fields, it identifies the partner by matching the values in these two HTTP header fields with the Partner CA Issuer and Partner Serial Number fields in the Partner tab configuration of the Config UI. The Partner CA Issuer contains the identity realm and the Partner Serial Number represents the partner’s identity for that realm.

The serial number uniquely identifies a specific certificate that the partner uses to identify itself. If you use the serial number for the partner configuration, the partner configuration needs to be updated to reflect a new serial number in case a partner’s certificate has expired.

When the partner renews its certificate after the certificate expiration, you do not need to update the TIBCO API Exchange Gateway partner configuration in case you use the subject distinguished name.

The following configuration setup is required on the Apache HTTP server so that TIBCO API Exchange Gateway can identify a partner based on the CAissuer and SerialNumber HTTP header fields:

•	Configure SSL engine options

Configure the SSL engine options to export the standard SSL/TLS related SSL_* environment variables. This makes the client certificate information available in the Apache server for further reference in the request processing steps. This includes the issuer distinguished name, the certificate serial number, and the subject distinguished name.

•	Enable mod_headers module

Enable the mod_headers module to control and modify the HTTP request and response headers.

•	Set RequestHeader directives

Set the RequestHeader directives that add specific CAissuer and SerialNumber HTTP headers to the incoming request. The header values are populated with the values retrieved from the SSL environment variables including the issuer distinguished name, the certificate serial number, or the subject distinguished name.

See Configure Client Certificate Identification Details On Apache HTTP Server for configuration steps.

Register Partners on Config UI

Register the partners in TIBCO API Exchange Gateway with digital certificate identification details. This means that you can add partners on the Config UI with the identity information that the client sends with its digital certificate.

See Registering Partners On Config UI for the procedure on configuration.

Copyright © Cloud Software Group, Inc. All Rights Reserved