One-way SSL
One-way SSL simply means that only the server certificate passes from the server to the client but not the other way around. Thus, only the server is authenticated. If we trust the server certificate’s issuer, we can establish an SSL link between our browser and the server [3].
Two-way SSL
When both client and server pass certificates to each other to establish an SSL link, we have mutual authentication via two-way SSL. Both sides now know the identity of the other from their respective certificates. The important thing to realize here is that, while the conditions for one-way SSL remain, the mirrored conditions also apply. In other words, the server also has to trust the issuer of the client certificate. Mutual authentication just means that both sides must trust each other. This forms the basis of Public Key Infrastructure [3].
Fundamentals of PKI
Public Key Infrastructure is a computerized form of message encryption using two keys; one is public and used by the sender to encrypt the message, the other is private and used by the recipient to decrypt the message [1]. It is essentially an arrangement surrounding the issuance of digital certificates and assignment of public keys. The issuance of a digital certificate is ultimately done by a certification authority as the result of the PKI process, which includes the binding of public keys to subscribing user identities after such identities have been validated.
The actual verification of user identities can be done by the certification authority itself, or by a separate registration authority. Once issued, however, the certification authority stamps and seals the PKI certificate with its unique digital signature. As a result the certificate holder is able to secure network communications and online transactions, as well as provide trusted third party, PKI -based, authentication of its business identity [2].
Configuration
Steps to configure CLIENT-CERT authentication-
Step 1: Configure two-way SSL in WebLogic Server
Step 2: Configure Default Identity Asserter
Step 3: Configure Web Application
Step 4: Test the configuration
Configure Two-Way SSL in WebLogic Server
First, we will test with Demo Identity and Demo Trust Store provided with WebLogic server. Later, we will discuss about configuring Custom Identity and Custom Trust Store.
Note: Demo Identity and Demo Trust Store should not be used in production environment.
Load BEA Test CA Certificate into Browser
Out of the box, WebLogic will present a certificate signed by the BEA test CA. You’ll need to add that CA certificate to your browser so that the server certificate will be trusted. Note that what you want to add to your browser is the certificate of the CA that issued the server certificate- not the server certificate itself. If you don’t add the CA certificate, SSL will still work but you will be prompted by your browser about an untrusted certificate [3].
To load the test CA certificate into your browser (Firefox 3.0 in this case) follow these steps-
Step 1: Go to Tools -> Options
Step 2: Select Advanced -> Encryption
Step 3: Click View Certificates
Step 4: Select Authorities
Step 5: Click Import
Step 6: Select $BEA_HOME/wlserver_10.3/server/lib/CertGenCA.der
Step 7: Select “Trust this CA to identify web sites”
Step 8: Click OK to save the settings.
Your browser will now trust certificates issued from the BEA test CA.
Note: Later, when you are done experimenting with the test certificate, be sure to remove the test CA certificate from your browser.
Create a Client Certificate
We will use a utility provided by BEA called CertGen to create a client certificate. This certificate will be issued by the BEA demo CA just like the demo server was. We will configure WLS to trust this client certificate when it is presented. To reiterate, the server trusts the client certificate issuer, not the client certificate directly [3].
To generate client certificate and keystore, follow the steps given below-
Step 1: Run $BEA_HOME/wlserver_10.3/server/bin/setWLSEnv.sh
Step 2: Use CertGen to create a client certificate as follows:
java utils.CertGen -certfile user.cer -keyfile userkey.key -keyfilepass weblogic -cn user
The CertGen command creates both the private key and certificate for the user specified as the CN (Common Name). The files are created in DER and PEM formats. Most browsers don’t recognize PEM/DER files, so we need to convert the key and certificate into a PKCS #12 file.
Step 3: Import key and certificate into a keystore of type PKCS#12 as follows:
java utils.ImportPrivateKey -keystore keystore.p12 -storepass weblogic -storetype pkcs12
-keypass weblogic -alias newalias -certfile user.cer.pem
-keyfile userkey.key.pem -keyfilepass weblogic
Load Client Certificate into Browser
The procedure for loading client certificates is almost the same as loading the CA certificate:
Step 1: Go to Tools -> Options
Step 2: Select Advanced -> Encryption
Step 3: Click View Certificates
Step 4: Select Your Certificates
Step 5: Click Import
Step 6: Select keystore.p12 (keystore generated in the previous step)
Step 7: Enter the store password (weblogic in the example)
Step 8: Click OK to save the settings.
Enforce Client Certificates over Two-Way SSL
To configure two-way SSL, demo identity store, trust store and enforce client certificates, follow the steps given below-
Step 1: Login to WebLogic Server Admin Console
Step 2: Select domain -> Environment -> Servers
Step 3: Select the server (For example: AdminServer)
Step 4: Ensure that SSL Listen Port is enabled (take a note of SSL port)
Step 5: Save the settings
Step 6: Select Keystores tab
Step 7: Select Keystores as Demo Identity and Demo Trust
Step 8: Save the settings
Step 9: Select SSL tab
Step 10: Select Identity and Trust Locations as Keystores
Step 11: Save the settings
Step 12: Click on Advanced in SSL tab
Step 13: Select Two Way Client Cert Behavior as Client Certs Requested and Enforced
Step 14: Restart WebLogic Server for the changes to take effect.
At this point, the server certificate is trusted by the browser since the browser trusts the test CA. The server is configured to trust the test CA, too, since it’s using the DemoTrust keystore. If the browser has a client certificate issued from the test CA, all should be well and SSL should work.
To test it, navigate to the WebLogic Console over SSL (https://localhost:7002/console). You should get prompted to supply a client certificate. Select the certificate and click OK to use it. You should then see the Console login page.
Next, we need to configure Default Identity Asserter to allow authentication using the client certificate.
Configure Default Identity Asserter
To configure Default Identity Store to analyze X.509 client certificate and map it to a valid user, follow the steps given below-
Step 1: Login to WebLogic Server Admin Console
Step 2: Select domain -> Security Realms -> realm
Step 3: Select Providers tab
Step 4: Select Authentication tab
Step 5: Select Default Identity Asserter
Step 6: Select X.509 as one of the Active types by moving it to Chosen box
Step 7: Save the settings
Step 8: Select Provider Specific tab
Step 9: Select Use Default User Name Mapper
Step 10: Select the Username Mapper Attribute Type as CN
Step 11: Remove any delimiter for Default Username Mapper Attribute
Step 12: Save the settings
Step 13: Restart WebLogic Server for the changes to take effect
Note: Default User Name Mapper will map the user name to a valid user in WebLogic user store
Configure Web Application
Web application must specify the authentication method as CLIENT-CERT in web.xml.
Test the Configuration
You are all set to test the configuration. Deploy the application to WebLogic server and request the protected resource. Server will authenticate you using the certificate and grant access to the protected resource.
Custom Identity and Custom Trust
The configuration that we just tested was with the demo identity and trust store provided by WebLogic. Instead of using the demo stores, we can use our custom identity and trust store. For development environment, we can generate a Self-Signed CA certificate using Java and WebLogic tools [See Reference 4].
We will follow these steps to get it done-
Step 1: Set the Environment
Step 2: Generate Server Private Key and Certificate
Step 3: Create the Identity Store
Step 4: Import the Certificate into a new Trust Keystore
Step 5: Install Server Certificate on Client
Step 6: Create a Client Certificate using Self-Signed CA Certificate
Step 7: Bundle Certificate and Key into a Keystore
Step 8: Import Trusted CA Certificate and Client Certificate into Browser
Step 9: Configure WebLogic Server with Identity and Trust Stores
Set the Environment
Run $BEA_HOME/wlserver_10.3/server/bin/setWLSEnv.sh script to set the environment.
Generate Server Private Key and Certificate
Use CertGen to create server private key and certificate as given below:
java utils.CertGen -selfsigned -certfile MyOwnSelfCA.cer
-keyfile MyOwnSelfKey.key -keyfilepass mykeypass
-cn “My Own Self CA”
Create the Identity Store
CertGen created a unique and secret Private Key for the server we are using and the Self-signed Root Certificate for us. But Java wants them packaged up neatly into a keystore. Fortunately BEA are a smart bunch and created a utility to help. Just to make sure there was no confusion about what it does, they called it ImportPrivateKey. Now run this-
java utils.ImportPrivateKey -keystore MyOwnIdentityStore.jks -storepass identitypass
-keypass keypassword -alias trustself
-certfile MyOwnSelfCA.cer.pem
-keyfile MyOwnSelfKey.key.pem -keyfilepass mykeypass
Import the Certificate into a new Trust Keystore
When the client asks the server for a connection, the server will only allow access if it trusts the signer of the client’s certificate. This is going to be the “My Own Self CA” and to make it happen we need our trusty MyOwnSelf certificate packed up into a separate keystore called the Trust Keystore. When the client presents it’s certificate, this is where the server will look to see if it trusts the signature of the CA. Now run this-
keytool -import -trustcacerts -alias trustself -keystore TrustMyOwnSelf.jks -file MyOwnSelfCA.cer.der -keyalg RSA
Install Server Certificate on Client
To have the client trust the server permanently, we need to install the certificate. You can follow the steps mentioned under Load BEA Test CA Certificate into Browser and import the certificate MyOwnSelfCA.cer.der into your browser. Alternatively, you can double click the certificate file and choose Install.
Create a Client Certificate using Self-Signed CA Certificate
It’s time to generate the certificate for the client. This time we want the Certificate to identify the client machine (usually the user of the machine – you can set up one client certificate per user and have more than one on a machine if you need to), and we want to ensure that the Client is linked to the Trusted CA Root Certificate we fabricated earlier. (This is why the ou (operating unit) of the client certificate must match the identity of the Trusted CA Certificate – in this case “My Own Self CA”.)
java utils.CertGen -certfile MyClientCert.cer -keyfile MyClientKey.key -keyfilepass clientkeypass
-cacert MyOwnSelfCA.cer.der -cakey MyOwnSelfKey.key.der -cakeypass mykeypass
-cn “My Client” -e “my.own@self.com” -ou “My Own Self CA”
Bundle Certificate and Key into a Keystore
Run the command as shown below-
java utils.ImportPrivateKey -keystore MyClientCert.p12 -storepass clientpass -storetype pkcs12
-keypass clientkeypass -alias clientcert -certfile MyClientCert.cer.pem
-keyfile MyClientKey.key.pem -keyfilepass clientkeypass
Import Client Certificate into Browser
Follow the steps mentioned under Load Client Certificate into Browser. Here, the keystore will be MyClientCert.p12 and store password will be clientpass.
Configure WebLogic Server with Identity and Trust Stores
In sections Create the Identity Store and Import the Certificate into a new Trust Keystore, we generated an Identity Keystore for Server to Client communication (to supply certificates to the client) and a Trust Keystore for Client to Server communication (to accept certificates supplied by the client). We now need to tell WebLogic to use them.
In the WebLogic Admin Console, jump to the Keystores tab (See Enforce Client Certificates over Two-Way SSL) and choose “Custom Identity and Custom Trust”. Enter the locations of your Identity and Trust keystores, the passphrases identitypass and trustpass respectively.
Now switch to SSL tab and enter the alias and the Private Key password (i.e ‘trustself’ and ‘keypassword’, respectively, in the example). When you have saved and activated your changes in the admin console, check the WebLogic command output window to verify that your Identity and Trust keystores were loaded with no problems.
You have now successfully configured the two-way SSL with Custom Identity and Custom Trust store. Rest of the configuration is same in both the cases. You need to configure Default Identity Asserter and make required changes to applications web.xml as mentioned earlier.
Troubleshooting
First step should be to enable the security log for your server. To enable the logs, follow the steps given below-
Step 1: Login to WebLogic Admin Console
Step 2: Select domain -> Environment -> Servers
Step 3: Select the Server (For example: AdminServer)
Step 4: Select Debug tab
Step 5: Expand the weblogic debug scope and enable security log
Step 6: Save the settings and restart server (if required)
After logging is enabled, you can check the server logs and look for a possible cause.
Note: You might see a lot of NoSuchAlgorithm exception that are being eaten by WebLogic server. WebLogic server looks for the best algorithm and in the process it generates those exceptions. Just ignore them.
Recent Comments