This article describes how to configure the SGD Secure Gateway to use client certificates to authenticate users. A client certificate is an SSL certificate that is installed on the client device, usually on a browser.

Client certificates can be used to enhance the security of the Gateway, by restricting access to those users who have a valid certificate.

Using client certificates with the Gateway involves the following steps:

(Optional) Generate a Client Certificate

This step describes how you can use the tools on the Gateway to generate a client certificate. You do not need to complete this step if you already have a client certificate and associated private key.

The examples in this article use a self-signed client certificate. For an enterprise deployment, use a client certificate signed by a trusted certificate authority (CA).

1. Log on to the Gateway host as superuser (root).
2. Generate a new key pair.
   Use the keytool command, as follows:

   # /opt/SUNWsgdg/java/jre-version/bin/keytool -genkeypair -keyalg RSA -alias mycert -keystore keystore.mycert -storepass letmein -keypass test123

   This command generates a client certificate and private key and stores them in a keystore called keystore.mycert, using the alias mycert. The password for the keystore is letmein. The password for the private key is test123.

3. Export the client certificate from the keystore.
   Use the keytool command, as follows:

   # /opt/SUNWsgdg/java/jre-version/bin/keytool -exportcert -alias mycert -keystore keystore.mycert -storepass letmein -file mycert.crt -rfc

   The client certificate is written to the file mycert.crt.

4. Export the client certificate key from the keystore.
   Use the KeyManager.jar application included with the Gateway, as follows:

   # /opt/SUNWsgdg/java/default/bin/java -jar /opt/SUNWsgdg/proxy/KeyManager.jar export --keyfile mycert_key.pem --keyalias mycert --keypass test123 --keystore keystore.mycert --storepass letmein

   The key is written to the file mycert_key.pem. The password used to access the key is test123.

Configure the Gateway to Use Client Certificates

1. Stop the Gateway.

   # /opt/SUNWsgdg/bin/gateway stop

2. Configure the Gateway so that HTTPS client connections require a client certificate.
   Add the <needClientAuth> entry to the /opt/SUNWsgdg/etc/gateway.xml file, as follows:

   <service id="http-ssl-service" class="SSL">
      <needClientAuth>true</needClientAuth>
          <!-- Decrypts HTTPS traffic -->
          <subService id="ssl-splitter">
                  <binding>*</binding>
          </subService>
   

Install the Client Certificate on the Gateway

1. Import the client certificate into the Gateway client certificate store.
   Use the keytool command, as follows:

   # /opt/SUNWsgdg/java/jre-version/bin/keytool -importcert -alias mycert -keystore /opt/SUNWsgdg/proxy/etc/keystore.client -file mycert.crt -storepass `cat /opt/SUNWsgdg/etc/password`

   This command imports the client certificate my_cert.crt into the Gateway client certificate store, keystore.client.

2. Start the Gateway.

   # /opt/SUNWsgdg/bin/gateway start

Install the Client Certificate and Key in the Browser

1. Convert the client certificate and key into a PKCS12 format file.

   # openssl pkcs12 -export -in mycert.crt -inkey mycert_key.pem -out mycert.p12

   This command converts the client certificate file mycert.crt and associated private key mycert_key.pem into a PKCS12 format certificate file mycert.p12.
   Client certificates imported into a browser certificate store must be in PKCS12 format.
   When saving the PKCS12 (.p12) file, openssl prompts you for a password. Note down the password. You need to use it when you import the client certificate into the browser.

2. Import the client certificate into the browser certificate store.
   Copy the client certificate to the client device.
   For details of how to import a client certificate, see the online documentation for your browser.
   The following figure shows the Certificate Import dialog for Internet Explorer.
   
   
3. Import the client certificate into the Java Virtual Machine (JVM) on the client device.

   This step is only required if you are using a Firefox browser.

   For example, on Windows client devices, you use the following tab in the Java Control Panel:
   Java Control Panel -> Security -> Certificates -> Client Authentication.
   The following figure shows the Import dialog for the Java Control Panel.
   

Access the Gateway Using Client Certificates

1. Restart your browser.
2. Log in to SGD through the Gateway.
   1. Go to the Gateway URL, such as https://gateway-server.example.com/sgd.
      The client authentication dialog is shown.
      
   2. Choose the client certificate and click OK.
      If client authentication is successful, the SGD login page is displayed.