Securing web applications
157Enabling client-certificate authentication
the name attribute of the application-policy element in the login-config.xml file is
simple-security-domain.
6.5.6 Selecting a strategy for forming the principal from the certificate
With password-based authentication, the user types in a username as a principal and a password as the credential. When implementing client-certificate authentication, it makes sense to use the certificate’s public key as the credential, but what would you use as the principal itself? If you look at the structure of a certificate, you could use
several parts of the certificate to represent the principal. In JBoss Web Server, you
can choose which part to use by configuring the realm setting in the JBoss Web
Server’s server.xml file. We talked about the realm in section 6.1.3, but let’s take another look at it.
<Realm className="org.jboss.web.tomcat.security.JBossWebRealm"
certificatePrincipal="org.jboss.security.auth.certs.SubjectDNMapping" allRolesMode="authOnly" />
The certificatePrincipal attribute configures which part of the client’s certificate
should be used as the principal. Out of the box, the certificatePrincipal attribute
is set to the SubjectDNMapping option shown. This option uses the certificate’s entire
Distinguished Name (DN) record. Table 6.4 shows you what other options you have.
We recommend trying the SubjectCNMapping option because it’s the easiest to set up
in your underlying security datastore where you store your principals and credentials. The option you define determines what part of the certificate is parsed and passed in as the principal to the login modules that authenticate and authorize the principal. You must make sure that this part of the certificate is stored in your underlying autho- rization datastore as well.
6.5.7 Adding principals and roles to the authorization datastore
You must add the principal and roles to the underlying authorization datastore (which
the login module stacked with the BaseCertLoginModule points to, as discussed in
Table 6.4 The different parts of the certificate that can be used for client-certificate authentication
certificatePrincipal option Part of the certificate used
as principal
org.jboss.security.auth.certs.SerialNumberIssuerDNMapping The serialNumber and
issuerDN org.jboss.security.auth.certs.SubjectCNMapping The value of the
SubjectDN’s CN element
org.jboss.security.auth.certs.SubjectDNMapping The entire SubjectDN
org.jboss.security.auth.certs.SubjectX500Principal The
step 4). The data that you populate into the datastore depends on the strategy you
selected for forming the principal name using the certificatePrincipal attribute
described in step 6. For example, if you used the SubjectCNMapping option, then you
add users that match the names in the Common Name (CN) element of the certificate.
Let’s say you have a certificate with the following output:
> keytool –printcert –file client.cer Certificate stored in file <client.cer> Owner: CN=Joe Schmoe, O=SomeCA, OU=SomeCAOrg Issuer: CN=Joe Schmoe, O=SomeCA, OU=SomeCAOrg Serial number: 47a22427
Valid from: Thu Jan 31 13:40:23 CST 2008 until: Sat Mar 10 13:40:23 CST 2012 Certificate fingerprints:
MD5: BA:82:F1:83:A8:13:82:F5:0F:67:00:99:13:48:1C:B7
SHA1: 14:A7:00:3A:EB:EE:3D:E3:EF:67:C9:68:16:22:D3:53:ED:84:D4:4E
If you used SubjectCNMapping in your server.xml realm and a UsersRolesLoginMod-
ule in your login-config.xml, the property file you use to store your roles might look
like this:
joe\ schmoe=rolea, roleb
The CN value in the certificate is Joe Schmoe, with camel-case lettering, but note the
lowercase lettering to define the principal in the datastore. When JBoss parses the
principal off of the certificate, it converts it to lowercase before comparing it to the value in the datastore, so you must add the name to your authorization datastore in lowercase letters. You also have to use an escape character (backslash) to support the space. You may have to do the same to support equals signs or other delimiters.
Although you stacked the UsersRolesLoginModule with the BaseCertLoginModule,
you need an empty user properties file to exist. You may face a similar case for other login modules.
6.5.8 Adding the client’s certificate to the server’s truststore
The truststore you pointed to in step 3 is the authentication datastore, so you must
import each client’s certificate into the truststore. You can use the keytool command
to do this, as follows:
keytool -import -alias "Joe Schmoe" -keystore server.truststore –file
➥ client.cer
The alias that you use must match the principal that would be parsed by the security framework. The alias acts as the principal name and the certificate acts as the creden-
tial. The value you use for the alias depends on the certificatePrincipal option
you used in step 6. The code snippet shows what it might look like if you used the
SubjectCNMapping value for the certificatePrincipal.
6.5.9 Creating a browser certificate
As described in section 6.4.4, you have to convert each client’s certificate to a format that your browser can handle.
159 Summary
So far, we’ve shown you examples where applications point to a specific security domain, but you may decide that you want a particular domain applied if no application- specific security domain is specified.
6.6
Changing the default security domain
If you don’t configure a security domain for an individual web application in the jboss- web.xml file but have defined security for various components in your web.xml file, then
JBoss defaults to the security domain configured using the defaultSecurityDomain
property of the WarDeployer bean defined in the following web server microcontainer
configuration file:
server/xxx/deployers/jbossweb.deployer/META-INF/war-deployers-jboss-beans.xml
Out of the box, the default security domain is configured as follows:
<property name="defaultSecurityDomain">
➥ java:/jaas/jboss-web-policy</property>
This property points to the security domain jboss-web-policy, which is defined in the
server/xxx/deploy/security/security-policies-beans.xml file. This security domain is
an extension of the other security domain defined in the server/xxx/conf/login-
config.xml file. The other security domain is configured to load usernames and roles
from files using the UsersRolesLoginModule. If you plan on using the default security
domain, you may want to define your own security domain in the login-config.xml file
and point the DefaultSecurityDomain attribute to it. Otherwise, you might change or
remove the definition for the default security domain.
6.7
Summary
We started this chapter by talking about the various configuration files used to config- ure security in web applications and how to tie that configuration in with the security domain configuration you learned about in chapter 4. We then gave a background on how challenge-response authentication works for web applications and talked about
the three challenge-response authentication mechanisms available in JBoss Web Server.
We showed how to configure basic authentication, digest authentication, and form authentication and talked about the benefits and drawbacks to each.
Next, we talked about authorization and showed how to configure role-based
access for different URLs. We also showed how to configure a URL so that any authen-
ticated user could access it, regardless of role assignment.
After learning about authentication and authorization, you learned how to encrypt
web communication. We talked about how to enable HTTPS by configuring the HTTP
connector to reference a secure certificate. You then learned how to enable a trans- port guarantee on an application to make sure that it can only be accessed over a secure channel. Last, you learned about mutual authentication and how the server can verify a browser certificate during the protocol handshaking.
Building on your fundamental knowledge of authentication and encryption, we taught you how to enable client-certificate authentication, whereby information on a
client’s certificate can be used as a client’s credentials. You learned how to change the default security domain that web applications are configured to use.
The nice thing about JBoss security is that a user who logs in through the web tier
of an application doesn’t have to re-authenticate against the EJB tier. As you’ll see
when we discuss EJB security in the next chapter, the EJB server integrates into the
same JBoss SX security framework and implements a similar configuration model.
6.8
References
Digest Access Authentication—http://www.zvon.org/tmRFC/RFC2069/Output/ longContents.html
Creating a PKCS12 certificate for Firefox—http://wiki.jboss.org/community/docs/DOC-11989
161