Configuring smart card login for a CCRC WAN Server

Answer

Note: This functionality is only supported on Linux and UNIX operating systems for the CCRC WAN Server. It is only supported on Windows for CTE clients.

Creating a Trust Association Interceptor (TAI):

1) For WAS 8.5.5.x, follow the instructions provided in the IBM Infocenter on “Developing a custom interceptor for trust associations” for WAS 8.0.0. The WAS 8.0.0 instructions linked below should be used for a WAS 8.5.5.x installation. The instructions can be found here: https://www-01.ibm.com/support/knowledgecenter/SSAW57_8.0.0/com.ibm.websphere.nd.doc/info/ae/ae/tsec_waci.html

2) Once you've built your class into a JAR you can drop it into the <WAS_INSTALL_DIRECTORY>/AppServer/lib/ext directory.

3) It's typical for the TAI to use the User Registry in WAS. In the example below, we'll setup WAS to use our local operating system but this is not required.

Configuring WebSphere security settings:

1) Log in to the WebSphere administrative console (e.g. https://<sever name>:16043/ibm/console).

2) Go to Security → Global security → “User account repository” and select the repository you'd like to use. We'll be using the “Local operating system” repository for this example.

1. Configure the repository. For our example, we need to set a “Primary administrative user name”. This should be set to whomever your WebSphere administrator will be.

2. Apply the changes and then Apply and Save the changes on the Global security page.

3) Go to Security → Global security and enable administrative security and application security:

4) Define additional Administrators with “Administrative user roles” if necessary.

5) In Global Security go to “Web and SIP security” → Trust association. Enable trust association.

6) Go to “Interceptors” under “Additional Properties” in the Trust association page.

7) Delete any trust association interceptors you will not be using and click “New...” to add your custom TAI. Specify the class name of the interceptor you created and any custom properties to be passed to the interceptor.

8) In our sample configuration the Interceptors page now looks like this:

9) In Global security click on “RMI/IIOP security” → CSIv2 inbound communications.

10) Under CSIv2 Transport Layer set “Client certificate authentication” to “Supported” and the Transport to “SSL-required”.

11) Go to Security → SSL certificate and key management → SSL configurations and click on the appropriate SSL node.

12) Under “Additional Properties” select “Quality of protection (QoP) settings”

13) Under “General Properties” set “Client authentication to “Supported”.

14) Go to Global security → RMI/IIOP Security → CSIv2 inbound communications → Manage endpoint security configurations → <your inbound node> → Key stores and certificates → <your trust store> → Signer certificates.

15) You'll need to add a signer certificate that will be in the smart card certificate chain to your trust store. For this example we added a root certificate.

16) Make sure all of the changes are applied and saved. Restart the WAS profile.

17) Edit the web.xml for the ccrc.war to restrict login to only allow certificate authentication. On UNIX this is in /opt/IBM/RationalSDLC/common/ccrcprofile/config/cells/dfltCell/applications/ccrc.ear/deployments/ccrc/ccrc.war/WEB-INF.
The web.xml in the deployed ccrc.war can be modified here without redeploying the application (CCRC WAN Server).

18) Change the login-config tag to the client certificate authentication method.

<login-config>
<auth-method>CLIENT-CERT</auth-method>
<login-config>

19) Since we will be requiring authentication via a client certificate this setting will apply to all URIs within our application. Add a new <security-constraint> for “/*” with the CONFIDENTIAL <transport-guarantee> to require SSL. It should look like this:

<security-constraint>
<web-resource-collection>
<web-resource-name>CCRC WAN Server</web-resource-name>
<url-pattern>/*</url-pattern>
</web-resource-collection>
<auth-constraint>
<role-name>User</role-name>
</auth-constraint>
<user-data-constraint>
<transport-guarantee>CONFIDENTIAL</transport-guarantee>
</user-data-constraint>
</security-constraint>

The <role-name> can be an existing role or a new one. We're creating a new one in our example here that we'll map in WebSphere.

20) If you added a new <role-name> above you'll also need a new <security-role> for that role:

<security-role>

<role-name>User</role-name>

<security-role>

21) Our example web.xml is now:

<?xml version="1.0" encoding="UTF-8"?>

<web-app id="WebApp_ID" version="2.4" xmlns="http://java.sun.com/xml/ns/j2ee&quot; xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance&quot; xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd">

<servlet>
<servlet-name>ccrc</servlet-name>
<servlet-class>com.ibm.rational.cc.server.servlet.CcServlet</servlet-class>
</servlet>

<servlet-mapping>
<servlet-name>ccrc</servlet-name>
<url-pattern>/*</url-pattern>
</servlet-mapping>

<security-constraint>
<web-resource-collection>
<web-resource-name>CCRC WAN Server</web-resource-name>
<url-pattern>/*</url-pattern>
</web-resource-collection>
<auth-constraint>
<role-name>User</role-name>
</auth-constraint>
<user-data-constraint>
<transport-guarantee>CONFIDENTIAL</transport-guarantee>
</user-data-constraint>
</security-constraint>

<login-config>
<auth-method>CLIENT-CERT</auth-method>
</login-config>

<security-role>
<role-name>User</role-name>
</security-role>

</web-app>

22) The last step in configuring WebSphere is to map our role to users. In the WebSphere Administrative Console go to Applications → Application Types → WebSphere enterprise applications → ccrc → “Security role to user/group mapping” and map your role from the web.xml settings to users, groups, or a special subject. We'll map the role “User” to the special subject “All Authenticated in Application's Realm” here:

23) Save the changes in WebSphere and restart the WAS profile.

Configuring CCRC:

1) Configure the java.security file in the ../RationalSDLC/common/JAVA/jre/lib/security directory to use the IBMCAC security provider by default:

security.provider.1=com.ibm.security.capi.IBMCAC

1. Note: Each security provider must use a different number so the existing security providers may need to be rearranged to allow IBMCAC to occupy the first slot.

2) Using the Certificate Manager tool (certmgr.msc), find the certificate you want to use in your Personal Certificate store.

3) Right click on the certificate and choose Properties. On the General page give the certificate the Friendly name “CTESmartCardCert”. The certificate you wish to use for CCRC authentication must have this Friendly name. Only one client certificate can have this Friendly name.

4) When connecting to a CCRC WAN Server that supports smart card authentication, select the “Use a smart card to login” option without filling in a user name or password. CCRC will then use your specified client certificate for authentication.