Recently I was asked to configure a web application using client certificate authentication. I did this is using Weblogic Application Server version 10.3, however the concepts for this apply to most application servers. The following sections describe the configuration changes that must be applied to the environment for this to work.

Web application

The web application needs to be modified to restrict access to resources and require the use of a client certification. In order to do this modify the deployment descriptor of the application by adding a security constraint:


Notice that the deployment descriptor above will secure all URLs that accessed using POST or GET. Modify this to match your application requirements.


After the application has been secured, you have to configure the application server to enable the SSL port. In Weblogic, this is done by performing the following steps:

  1. In the Weblogic console open the server configuration Environment --> Server --> <Server_Name> (usually AdminServer). Open the Configuration/General tab and check the option "SSL Listener Port Enabled". Save your changes
  2. Next configure the server identity and trust stores. This is done by going into the console and selecting Environment --> Server --> <Server_Name>. Open the Configuration/KeyStores tab and select Custom Identity and Java Standard Trust. Provide the keystore and password where the identity for the server is located.
  3. Now you must specify which entry in the keystore provided must be used to identify the server, for this go to Environment Server <Server_Name> and select the Configuration/SSL tab. In the Identity section provide the alias and password for the key to be used.
  4. In the same tab as the previous step (Configuration/SSL) expand the Advance section. Update the drop down for the "Two way Client Cert Behavior" to Client Certs Requested and Enforced. Notice that depending on your environment you may need to disable Host name verification in the same section.


If you follow the steps on the previous section, your server will require that all clients present a client certificate and use the corresponding SSL port. Once the SSL Handshake successfully occurs then the user must be authenticated. Here are the steps to authenticate a user based on the certificate presented:

  1. Modify or create a Default Identity Asserter. By default the asserter is setup to assert AutheticatedUser tokens, you must modify it to authenticate X.509 tokens. For this go to the Weblogic console Security Realms --> <realm name> (by default this is called myrealm). Select the Providers/Authentication tab and either create or choose the DefaultIdentityAsserter. In the Configuration/Common tab for the asserter, modify the Active Types to include only X.509.
  2. In the Configuration/Provider Specific tab for the asserter modify the "Default User Name Mapper Attribute Delimiter" option to , (comma), set the "Default User Name Mapper Attribute Type" to CN and check the "Use Default User Name Mapper" option.

The Default Identity Asserter will use the embedded LDAP server to map authenticated users. This implies that all the clients that want to authenticate using certificates must be added to the users in Weblogic (in the console go to Security Realms --> <realm name> and select the Users and Groups/Users tab). If you want to use a different LDAP server you must create a different asserter of type LDAPX509IdentityAsserter.


Once a user has been authenticated, the next step is either to authorize or deny the usage of the web application to the user. This is done by modify the security policy of the application deployed.

  1. Deploy your application into the application server.
  2. In the Weblogic console select the application from the Deployments list.
  3. Navigate to the Security/Policies tab and click on "Add Conditions". This will open a new page for you to select a "Predicate List", select Users from the drop down (depending on your setup you might want to select a different option from the list e.g. Groups, Roles, etc.) and click "Next".
  4. In the next page, type the user name in the "User Argument Name" field and click "Add". Continue adding as many users as needed.
  5. Once all the users have been added click "Finish" and then "Save"
  6. Restart the server

After performing these steps your application should require the use of certificates and, if the client presents the correct certificate, the user should be able to access and use the application. Obviously not everything goes as planned, so if you have problems during this setup try the following:

  1. Add the jvm option: This should provide you details regarding the SSL handshake and related errors.
  2. Change the Severity levels for the log messages in the server. In the Weblogic console go to Environment --> Servers --> AdminServer and select the Logging/General tab. Expand the Advance section and modify the "Severity Level" drop down to Debug for the Log file and/or the standard out.
  3. Also you can display further information regarding security events in Weblogic (such as the Identity Asserter interactions). In the same Logging/General tab as the previous step change the severity priority for the Security category by typing Security=Debugin the "Logger severity properties" field.