jGuard reference documentation

jGuard distinguish 3 types of "users" in a J2EE environment:

since release 1.0.0 , jGuard provides two Security scopes, on authentication and authorization. these scopes affect jGuard javax.security.auth.login.Configuration and java.security.policy implementations.

AuthenticationManager implementations aims to do Create, Read, Update, Delete (CRUD) operations on users and roles of the application. These Users and roles are present in the datasource authentication. This datasource (database, XML and so on..), is also the same one used for the authentication process which involve LoginContext, Configuration and LoginModules.

Authentication configuration in jGuard, is done via the jGuardAuthentication.xml file.

goals of this configuration file is to:

This class is the main entry point to the Authentication Process. it defines :

this class handle the way to grab informations contained into information from a protocol, to fill callbacks (used by loginmodules) to authenticate the user. So, LoginModules can use the same callbacks but with different CallbackHandler depending on the situation. jGuard provides different callbackHandler like JMXCallbackHandler, SwingCallbackHandler ,and HttpServletCallbackHandler.

this class defines which loginModules are involved in the authentication process, for a defined application (identified by its name). Each application has its own loginModules stack. With some special keywords to customize the mechanism.

Object resulting from a successful authentication. it represents a "real" entity like a user, a machine, and so on.... it contains some Principals and some credentials present in relative Sets.

jGuard provides a mechanism that allows to automatically enable or disable a role (RolePrincipal) based on user credentials. This feature is defined in the attribute “definition” of “principalRef” tag. This attribute must evaluate “true” or “false”. For example, we could have in jGuardUsersPrincipals.xml the following:

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<authentication  xmlns="http://jguard.sourceforge.net/xsd/jGuardUsersPrincipals_1.1.0"
xmlns:xs="http://www.w3.org/2001/XMLSchema-instance"
xs:schemaLocation="http://jguard.sourceforge.net/xsd/jGuardUsersPrincipals_1.1.0 jGuardUsersPrincipals_1.1.0.xsd">
  <principals>
      <principal>
        <name>admin</name>
        <class>net.sf.jguard.core.principals.RolePrincipal</class>
        <applicationName>jguard-struts-example</applicationName>
        <organizationRef>myenterpriseId</organizationRef>
      </principal>
      <principal>
        <name>guest</name>
        <class>net.sf.jguard.core.principals.RolePrincipal</class>
        <applicationName>jguard-struts-example</applicationName>
        <organizationRef>system</organizationRef>
      </principal>
      <principal>
        <name>role3</name>
        <class>net.sf.jguard.core.principals.RolePrincipal</class>
        <applicationName>anotherApplication</applicationName>
        <organizationRef>system</organizationRef>
      </principal>
  </principals>
  <users>
      <user>
     <privateCredentials>
       <credential>
          <id>login</id>
          <value>admin</value>
       </credential>
       <credential>
          <id>password</id>
          <value>admin</value>
       </credential>
     </privateCredentials>

     <publicCredentials>
       <credential>
          <id>firstname</id>
          <value>Rick</value>
       </credential>
       <credential>
          <id>lastname</id>
          <value>Dangerous</value>
       </credential>
       <credential>
          <id>location</id>
          <value>Paris</value>
       </credential>
     </publicCredentials>

     <principalsRef>
          <principalRef name="admin" applicationName="jguard-struts-example" definition="${subject.publicCredentials.location.contains('Paris')}" active="true"/>
          <principalRef name="role3" applicationName="anotherApplication"/>
     </principalsRef>
     <organizationRef>system</organizationRef>
   </user>
   <user>
   <privateCredentials>
   <credential>
        <id>login</id>
        <value>guest</value>
   </credential>
   <credential>
        <id>password</id>
        <value>guest</value>
   </credential>
   </privateCredentials>
   <publicCredentials/>
        <principalsRef>
          <principalRef name="guest" applicationName="jguard-struts-example" />
        </principalsRef>
        <organizationRef>system</organizationRef>
   </user>
  </users>
<organizations>
    <organizationTemplate>
        <userTemplate>
                <privateRequiredCredentials>
                          <credTemplateId>login</credTemplateId>
                          <credTemplateId digestNeeded="true">password</credTemplateId>
                  </privateRequiredCredentials>
                  <publicRequiredCredentials>
                        <credTemplateId>firstname</credTemplateId>
                    <credTemplateId>lastname</credTemplateId>
                        <credTemplateId>location</credTemplateId>
                  </publicRequiredCredentials>
                  <privateOptionalCredentials>
                        <credTemplateId>country</credTemplateId>
                        <credTemplateId>religion</credTemplateId>
                  </privateOptionalCredentials>
                  <publicOptionalCredentials>
                        <credTemplateId>hobbies</credTemplateId>
                  </publicOptionalCredentials>
                  <principalsRef>
                     <principalRef name="admin" applicationName="jguard-struts-example"/>
                     <principalRef name="role3" applicationName="anotherApplication"/>
                  </principalsRef>
                </userTemplate>
	      <credentials>
                <credTemplateId>id</credTemplateId>
             </credentials>
	      <principalsRef>
	         <principalRef name="admin" applicationName="jguard-struts-example"/>
                 <principalRef name="role3" applicationName="anotherApplication"/>
	      </principalsRef>
</organizationTemplate>
    <organization>
          <userTemplate>
                  <privateRequiredCredentials>
                          <credTemplateId>login</credTemplateId>
                          <credTemplateId digestNeeded="true">password</credTemplateId>
                  </privateRequiredCredentials>
                  <publicRequiredCredentials>
                        <credTemplateId>firstname</credTemplateId>
                    <credTemplateId>lastname</credTemplateId>
                        <credTemplateId>location</credTemplateId>
                  </publicRequiredCredentials>
                  <privateOptionalCredentials>
                        <credTemplateId>country</credTemplateId>
                        <credTemplateId>religion</credTemplateId>
                  </privateOptionalCredentials>
                  <publicOptionalCredentials>
                        <credTemplateId>hobbies</credTemplateId>
                  </publicOptionalCredentials>
                  <principalsRef>
                     <principalRef name="admin" applicationName="jguard-struts-example"/>
                     <principalRef name="role3" applicationName="anotherApplication"/>
                  </principalsRef>
          </userTemplate>
            <credentials>
                <credential>
                        <id>id</id>
                        <value>system</value>
                 </credential>
                <credential>
                        <id>creation date</id>
                        <value>1965</value>
                 </credential>
             </credentials>
            <principalsRef>
                <principalRef applicationName="jguard-struts-example" name="guest"/>
                <principalRef name="admin" applicationName="jguard-struts-example" />
            </principalsRef>
    </organization>
</organizations>
</authentication>

The application could provide a way to allow the user to change its credential “loggedProject” between “ProjectA” and “ProjectB”. If the users chooses “ProjectA”, jGuard will automatically enable those roles where attribute “definition” evaluates “true”. You could use more complex expressions using logical operators, for example:

(subject.publicCredentials.loggedProject.contains('ProjectA') || subject.publicCredentials.loggedProject.contains('ProjectB')) && subject.privateCredentials.login.contains('userA')

RolePrincipal ppal = (RolePrincipal)AuthenticationManagerFactory.getAuthenticationManager().getRole(subject, role, applicationName);
String roleDefinition = ppal.getDefinition();

AuthenticationManagerFactory.getAuthenticationManager().updateRoleDefinition(subject, roleName, applicationName, roleDefinition);

jGuard can use a cryptographic hash function to avoid password to be stored in clear on the server. This function has the characteristic to produce a unique digest of any string. So, a password 'secret1' will produce with one of these functions a digest like '1gE1r'. a password 'secret2' will produce a digest like 'sF42'. For each password, a different digest will be produced. So,each original password will have its unique digest.

another characteristic is that it is very difficult to know which password is the origin of a related digest . So, if we store 'digested' password and not the original, anyone which will read these ones will not have the original password. But when we receive the password from the end user, we calculate the digest of it, and compare it with the one stored on the webapp using jGuard.

Cryptographic hash functions also called MessageDigest algorithms, are available in Java. Different algorithms are supported. You need to refer to the documentation of your JVM vendor, especially the Java Cryptography Architecture section. For example, many JVM vendors provides these algorithms:

Other ones are also available. To use one algorithm in jGuard, you have to use the right code related to the algorithm chosen like the ones listed above. To use this algorithm, you have to uncomment the digestAlgorithm markup in the jGuardAuthentication.xml file and put into your messageDigest algorithm code.

<digestAlgorithm>MD5</digestAlgorithm>

password salting is described on wikipedia. Password are impossible to know if you have only their digest. But if you store the digest of some popular password and the origin in some big tables, you can lookup easily the origin based on the digest. These tables are called rainbow tables.

Password salting is used to prevent some attackers to use rainbow tables. These tables are based on a known password origin. But if you modify the origin with a 'salt' specific to your application, it will be impossible to create rainbow tables with all the possibilities of salt.

For example, if you concatenate 'passord1' with the salt 'salt1' before to calculate the digest, the result will be different and very difficult to know. To use salt in conjunction of digest algorithm functions (you cannot only use salt without digest algorithm), you have to uncomment in the jGuardAuthentication.xml file the salt markup and put into it the salt chosen. Be aware that sometimes, some rainbow tables also contains some short salts. To be very safe, you should use long salts.

<salt>qsd846ss2q6ds4</salt>

Authorization part is involved to determine which resources will be accessible from an authenticated user. jGuard uses an Access Control model which involves the use of roles domains and permissions concepts.

Roles are present in authentication and authorization parts, and represent the unique link between these two parts.

To configure authorization of your web application, you have to :

java.security.Policy,principal,permission....

the default implementation provided delegates all security check to the current java.security.Policy implementation.

Authorization configuration in jGuard, is done via the jGuardAuthorization.xml file.

goals of this configuration file is to: