Certificates, CLIENT-CERT Authentication and Authorization

["Edwin K. Brown" <ek...@vsticorp.com>]

I’m doing this to provide an _outline_ of what is needed to be done to get CLIENT-CERT authentication and authorization working in Tomcat 6. This is high level because each implementation will have to be done to suit your own needs.

 

This first part deals with the JAAS related code that you have to create:

 

*	The Tomcat documentation states that the org.apache.catalina.realm.JAASRealm has to be used to get this working. Actually, the JAASRealm should be extended or you create a class that extends org.apache.catalina.realm.RealmBase. For purposes of this post, lets call this class CertJASSRealm.
*	In CertJASSRealm, the authenticate(X509Certificate certs[]) method needs to be over-ridden/implemented to perform the certificate validation.
*	In CertJASSRealm, the getPrincipal(String username) and getPrincipal(String username, String subject) methods needs to be over-ridden/implemented to create the principal.
*	The Tomcat documentation states that it is best to implement your own Role and User class, and that is definitively the case!
*	Create a class to handle the role. 
*	Create a class to handle the user. This seems to be one of the keys to getting this right. Let’s call this class CertJASSUser. The getRoles() method needs to be implemented to retrieve the roles associated with this user. In the “demo” that I did, I had this return a set array of roles. I imagine in “the real world,” this would go to some external source like LDAP, a database, or a file, to retrieve roles, if any, for the user.
*	In CertJAASUser, implement hasRole(String role) that determines if the user has the role name passed in.
*	Implement a LoginModule class and a CallbackHandler class to the JAAS specification to suit your needs. 
*	Let’s call the CallbackHandler class CertCallbackHandler. I created a method that sets the certificates, public void setCerts(X509Certificate[] certs), for use later on during the login() process.
*	Let’s call the LoginModule implementation CertLoginModule. The initialize(Subject, CallbackHandler, Map, Map)  method should do any initialization needed. The login() method should do the “login” using the certificates from the CertCallbackHandler object.
*	Make sure you create the JAAS configuration file. The name of the module in this example is CertJaas.

 

This second part deals with SSL authentication. This has to make it possible to get the authentication with certificates:

*	Create a class that extends org.apache.catalina.authenticator.AuthenticatorBase. Let’s call this class CertSSLAuthenticator
*	Implement authenticate(Request request, Response response, LoginConfig config). The TOMCAT class SSLAuthenticator is a good class to use as a model for what to do for the authentication process. I think CRL lookup or OCSP could be used in this method.

 

 

This third part deals with what you have to do to get TOMCAT to recognize that you have JAASRelam code that you want to be used instead of what TOMCAT provides. Please note that JAASRealm is the ONLY JAAS implementation that TOMCAT will recognize “out of the box” without make the following changes. Believe me, if you don’t do the following, you will NOT get it working properly. You will have to extract, modify, and replace some files in catalina.jar.

*	Make a copy of catalina.jar.
*	Extract org/apache/catalina/authenticator/mbeans-descriptors.xml
*	Copy the mbean tag with attribute name “SSLAuthenticator”.
*	Change the name attribute to the name of the file you created to do the SSL authentication in the second part. In this case, the name would be CertSSLAuthenticator.
*	Modify the type attribute to the full class name of the SSL authenticator class.
*	Save the file and replace it in the catalina jar.
*	Extract org/apache/catalina/startup/Authenticators.properties
*	There is an entry for CLIENT-CERT: CLIENT-CERT=org.apache.catalina.authenticator.SSLAuthenticator. Change the class name to the class of the SSL authenticator class created. In this case, CertSSLAuthenticator.
*	Save the file and replace it in catalina.jar

 

The above was done because by default, TOMCAT uses it’s own files and no matter how you override things, your own code doesn’t get called.

 

 

The fourth part deals with the server.xml configuration.

*	The for the realm, an example would be as follows:

<Realm classname=”example.CertJAASRealm” appName=”CertJass” userClassNames=”example.CertJASSUser”

roleClassNames=”example.CertJASSRole” resourceName=”CertJass” />

 

 

That is an outline of what I did to get it working. I’m sending this so that Google will find it and give it as a _possible_ way of getting it done. It appears to me that the TOMCAT team could make this a lot easier to do.

 

Ed Brown
Senior Software Architect
Vision Systems & Technology, Inc.

________________________________

6021 University Boulevard, Suite 360 ▪ Ellicott City ▪ Maryland ▪ 21043
Tel: 443.283.0135 ▪ Fax: 410.418.8580
Email: ekbrown@vsticorp.com
Web: http://www.vsticorp.com/

 

Re: Certificates, CLIENT-CERT Authentication and Authorization

[Stephen More <st...@gmail.com>]

There seems to be good documentation for configuring Realms. I
currently have a JAASRealm working by implementing a
javax.security.auth.spi.LoginModule


I have found very little documentation for custom Authenticators. Your
_outline_ is helpful, but I am still struggling.

My class which extends
org.apache.catalina.authenticator.BasicAuthenticator contains:

org.apache.catalina.Realm realm = context.getRealm();
log.trace( "Info: " + realm.getInfo() );

The logs are outputting "Info: org.apache.catalina.realm.RealmBase/1.0"

Any clue on how to get it to use "org.apache.catalina.realm.JAASRealm/1.0" ?

My web.xml still contains

<login-config>
        <auth-method>BASIC</auth-method>
        <realm-name>CUSTOMRealm</realm-name>
    </login-config>


Thanks for any insight or pointers to documentation on Authenticators.
-Steve More


On 9/26/07, Edwin K. Brown wrote:
> I'm doing this to provide an _outline_ of what is needed to be done to get CLIENT-CERT authentication and authorization working in Tomcat 6. This is high level because each implementation will have to be done to suit your own needs.
>
>
>
> This first part deals with the JAAS related code that you have to create:
>
>
>
> *       The Tomcat documentation states that the org.apache.catalina.realm.JAASRealm has to be used to get this working. Actually, the JAASRealm should be extended or you create a class that extends org.apache.catalina.realm.RealmBase. For purposes of this post, lets call this class CertJASSRealm.
> *       In CertJASSRealm, the authenticate(X509Certificate certs[]) method needs to be over-ridden/implemented to perform the certificate validation.
> *       In CertJASSRealm, the getPrincipal(String username) and getPrincipal(String username, String subject) methods needs to be over-ridden/implemented to create the principal.
> *       The Tomcat documentation states that it is best to implement your own Role and User class, and that is definitively the case!
> *       Create a class to handle the role.
> *       Create a class to handle the user. This seems to be one of the keys to getting this right. Let's call this class CertJASSUser. The getRoles() method needs to be implemented to retrieve the roles associated with this user. In the "demo" that I did, I had this return a set array of roles. I imagine in "the real world," this would go to some external source like LDAP, a database, or a file, to retrieve roles, if any, for the user.
> *       In CertJAASUser, implement hasRole(String role) that determines if the user has the role name passed in.
> *       Implement a LoginModule class and a CallbackHandler class to the JAAS specification to suit your needs.
> *       Let's call the CallbackHandler class CertCallbackHandler. I created a method that sets the certificates, public void setCerts(X509Certificate[] certs), for use later on during the login() process.
> *       Let's call the LoginModule implementation CertLoginModule. The initialize(Subject, CallbackHandler, Map, Map)  method should do any initialization needed. The login() method should do the "login" using the certificates from the CertCallbackHandler object.
> *       Make sure you create the JAAS configuration file. The name of the module in this example is CertJaas.
>
>
>
> This second part deals with SSL authentication. This has to make it possible to get the authentication with certificates:
>
> *       Create a class that extends org.apache.catalina.authenticator.AuthenticatorBase. Let's call this class CertSSLAuthenticator
> *       Implement authenticate(Request request, Response response, LoginConfig config). The TOMCAT class SSLAuthenticator is a good class to use as a model for what to do for the authentication process. I think CRL lookup or OCSP could be used in this method.
>
>
>
>
>
> This third part deals with what you have to do to get TOMCAT to recognize that you have JAASRelam code that you want to be used instead of what TOMCAT provides. Please note that JAASRealm is the ONLY JAAS implementation that TOMCAT will recognize "out of the box" without make the following changes. Believe me, if you don't do the following, you will NOT get it working properly. You will have to extract, modify, and replace some files in catalina.jar.
>
> *       Make a copy of catalina.jar.
> *       Extract org/apache/catalina/authenticator/mbeans-descriptors.xml
> *       Copy the mbean tag with attribute name "SSLAuthenticator".
> *       Change the name attribute to the name of the file you created to do the SSL authentication in the second part. In this case, the name would be CertSSLAuthenticator.
> *       Modify the type attribute to the full class name of the SSL authenticator class.
> *       Save the file and replace it in the catalina jar.
> *       Extract org/apache/catalina/startup/Authenticators.properties
> *       There is an entry for CLIENT-CERT: CLIENT-CERT=org.apache.catalina.authenticator.SSLAuthenticator. Change the class name to the class of the SSL authenticator class created. In this case, CertSSLAuthenticator.
> *       Save the file and replace it in catalina.jar
>
>
>
> The above was done because by default, TOMCAT uses it's own files and no matter how you override things, your own code doesn't get called.
>
>
>
>
>
> The fourth part deals with the server.xml configuration.
>
> *       The for the realm, an example would be as follows:
>
> <Realm classname="example.CertJAASRealm" appName="CertJass" userClassNames="example.CertJASSUser"
>
> roleClassNames="example.CertJASSRole" resourceName="CertJass" />
>
>
>
>
>
> That is an outline of what I did to get it working. I'm sending this so that Google will find it and give it as a _possible_ way of getting it done. It appears to me that the TOMCAT team could make this a lot easier to do.
>
>
>
> Ed Brown
> Senior Software Architect
> Vision Systems & Technology, Inc.
>
> ________________________________
>
> 6021 University Boulevard, Suite 360 ▪ Ellicott City ▪ Maryland ▪ 21043
> Tel: 443.283.0135 ▪ Fax: 410.418.8580
> Email: ekbrown@vsticorp.com
> Web: http://www.vsticorp.com/
>
>
>
>