Version 10

    Please use Project PicketBox


    and disregard the content below.  ( <=    ATTENTION)

     

     

     

     

     

     

     

     

     

     

    IDTrust

     

    Typically, applications running in a Java environment need to perform security functions such as Authentication, Authorization and Auditing.

     

    Requirements/Background:

    You need security libraries that run in a Java environment. You say, "I have a Java program. I can download some libraries. I do not need Tomcat or JBoss AS or any containers. Just plain Java. Anything for me?".  If this is the case, please read on.

     

    Installation

     

    Version: 2.0.2.CR1

     

    Grab the following jar:

    IDTrust:  http://repository.jboss.org/maven2/org/jboss/security/jboss-idtrust/2.0.2.CR1/jboss-idtrust-2.0.2.CR1.jar

     

    Dependencies:

    SPI Bare, Identity SPI, Authorization SPI and JBossSX Bare.

     

    JBossSecuritySPI Bare: http://repository.jboss.org/maven2/org/jboss/security/jboss-security-spi-bare/2.0.2.SP6/jboss-security-spi-bare-2.0.2.SP6.jar

    Identity SPI: http://repository.jboss.org/maven2/org/jboss/security/identity-spi/2.0.2.SP6/identity-spi-2.0.2.SP6.jar

    Authorization SPI: http://repository.jboss.org/maven2/org/jboss/security/authorization-spi/2.0.2.SP6/authorization-spi-2.0.2.SP6.jar

    JBossSX Bare: http://repository.jboss.org/maven2/org/jboss/security/jbosssx-bare/2.0.2.SP6/jbosssx-bare-2.0.2.SP6.jar

     

    Other dependencies :

     

    Stax API, JAXBv2 . These are provided by JDK6 onwards. If you are running on JDK5, then pick (http://repository.jboss.org/maven2/stax/stax-api/1.0.1/stax-api-1.0.1.jar) and JAXBv2 api/impl(http://repository.jboss.org/maven2/sun-jaxb/jaxb-api/2.1.9/jaxb-api-2.1.9.jar) (http://repository.jboss.org/maven2/sun-jaxb/jaxb-impl/2.1.9/jaxb-impl-2.1.9.jar)

     

    Authentication

     

    Authentication involves verification of a Principal against some credential. JAAS is the preferred mechanism in the Java world for implementing authentication. Now if your authentication has to work with a DB or a LDAP as the store for information about the actor (user, program etc), then you will need to write the login module.

     

    JBoss IDTrust provides the same login modules available in your favorite version of the JBoss Application Server, to run in any standalone environment.

     

    Let us see some code examples for authentication:

     

    import java.security.Principal;
    import javax.security.auth.Subject;
    import org.jboss.security.AuthenticationManager;
    import org.jboss.security.config.IDTrustConfiguration;
    import org.jboss.security.idtrust.api.factories.SecurityFactory;
    
    private final String securityDomainName = "test";
    
    //Specify the configuration file
    String configFile = "config/authentication.conf";
    IDTrustConfiguration idtrustConfig = new IDTrustConfiguration();
    idtrustConfig.config(configFile);
    //Get the AuthenticationManager from the factory
    AuthenticationManager am =
         SecurityFactory.getAuthenticationManager(securityDomainName);
    assertNotNull(am);
         
    Subject subject = new Subject();
    Principal principal = getPrincipal("anil");
    Object credential = new String("pass");
         
    boolean result = am.isValid(principal, credential); 
    assertTrue("Valid Auth", result);
    result = am.isValid(principal, credential, subject);
    assertTrue("Valid Auth", result);
    assertTrue("Subject has principals",
       !subject.getPrincipals().isEmpty());
    

     

    The key here is to have a configuration file (this is the authentication.conf)

    as follows available on the classpath:

    <?xml version='1.0'?> 
     
    <policy xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
             xsi:schemaLocation="urn:jboss:security-config:5.0"
             xmlns="urn:jboss:security-config:5.0"
             xmlns:jbxb="urn:jboss:security-config:5.0">
       <application-policy name = "test"> 
           <authentication>
              <login-module code = "org.jboss.security.auth.spi.UsersRolesLoginModule"
                 flag = "required">  
              </login-module> 
           </authentication> 
        </application-policy>  
    </policy>
    

     

    Authorization

     

    Authorization is the tricky part. Authentication process is finite with fixed type of parameters (username/password, X509 Certificates) etc involved in the decision making. But the authorization space is quite infinite that any number of disparate parameters can be involved in the decision making.

     

    You can get access to the AuthorizationManager via the SecurityFactory class. You also need to familiarize with the concept of a Resource.

     

    import java.security.Principal;
    import java.util.HashMap;
    import java.util.Map;
    
    import javax.security.auth.Subject;
    
    import junit.framework.TestCase;
    
    import org.jboss.security.AuthenticationManager;
    import org.jboss.security.AuthorizationManager;
    import org.jboss.security.authorization.AuthorizationContext;
    import org.jboss.security.authorization.Resource;
    import org.jboss.security.authorization.ResourceType;
    import org.jboss.security.config.IDTrustConfiguration;
    import org.jboss.security.idtrust.api.factories.SecurityFactory;
    
    //Let us define a security domain - for more info look at config file
    private final String securityDomainName = "test";
    
    //Define a configuration file available on the classpath
    private final String configFile = "config/authorization.conf";
    
    //Read in the configuration
    IDTrustConfiguration idtrustConfig = new IDTrustConfiguration();
    idtrustConfig.config(configFile);
    
    AuthenticationManager am = SecurityFactory.getAuthenticationManager(securityDomainName);
    assertNotNull(am);
         
    Subject subject = new Subject();
    Principal principal = getPrincipal("anil");
    Object credential = new String("pass");
         
    boolean result = am.isValid(principal, credential, subject);
    assertTrue("Valid Auth", result);
    assertTrue("Subject has principals", !subject.getPrincipals().isEmpty());
         
    AuthorizationManager authzM = SecurityFactory.getAuthorizationManager(securityDomainName);
    assertNotNull(authzM);
    Resource resource = getResource();
    int decision = authzM.authorize(resource, subject);
    assertTrue(decision == AuthorizationContext.PERMIT);
    

     

    The getResource() method is as follows:

    private Resource getResource()
    {
       return new Resource()
       {
           public ResourceType getLayer()
           {
              return ResourceType.IDTRUST;
           }
    
           public Map<String, Object> getMap()
           {
              return new HashMap<String,Object>();
           }
          };
    }
    

    You will probably implement your implementation of the org.jboss.security.authorization.Resource interface.

     

    The authorization.conf configuration file looks as follows:

    <?xml version='1.0'?> 
     
    <policy xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
             xsi:schemaLocation="urn:jboss:security-config:5.0"
             xmlns="urn:jboss:security-config:5.0"
             xmlns:jbxb="urn:jboss:security-config:5.0">
       <application-policy name = "test"> 
           <authentication>
              <login-module code =
          "org.jboss.security.auth.spi.UsersRolesLoginModule"
                 flag = "required"> 
                 <module-option name = "name">1.1</module-option>
                 <module-option name = "succeed">true</module-option>
                 <module-option name = "throwEx">false</module-option> 
              </login-module> 
           </authentication> 
           <authorization>
              <policy-module 
                code=
    "org.jboss.security.idtrust.impl.plugins.authorization.
    IDTrustAuthorizationModule">
                <module-option name="roles">validuser</module-option>
              </policy-module>
           </authorization>
        </application-policy>  
    </policy>
    

     

    This configuration file defines both the authentication as well as the authorization modules.

     

    The IDTrustAuthorizationModule verifies that the Subject has a rolegroup called as "Roles" and in it contains

    the configured roles (in this example, the subject should have the "validUser" role).

    Source: http://anonsvn.jboss.org/repos/jbossas/projects/security/security-standalone/trunk/idtrust-impl/src/main/java/org/jboss/security/idtrust/impl/plugins/authorization/IDTrustAuthorizationModule.java

     

    Please feel free to write your own AuthorizationModule implementation.

     

    You can also make use of the ACL framework that is provided as part of JBoss Security libraries that exist as dependencies of IDTrust. They are available via the AuthorizationManager.getEntitlements method. Only thing you have to remember is that you will be bringing a lot more run time dependencies such as JPA, Hibernate etc.

     

    Auditing

     

    Auditing is key to security operations. You want to be able to audit security events.

     

    You can use the "org.jboss.security.audit.providers.LogAuditProvider" to log audit events in the log4j log.

     

    Some code:

    import java.security.Principal;
    import java.util.HashMap;
    import java.util.Map;
    
    import javax.security.auth.Subject;
    
    import junit.framework.TestCase;
    
    import org.jboss.security.AuthenticationManager;
    import org.jboss.security.audit.AuditEvent;
    import org.jboss.security.audit.AuditLevel;
    import org.jboss.security.audit.AuditManager;
    import org.jboss.security.config.IDTrustConfiguration;
    import org.jboss.security.idtrust.api.factories.SecurityFactory;
    import org.jboss.security.audit.providers.LogAuditProvider;
    
    private final String securityDomainName = "test";
    
    //Read in the configuration
    String configFile = "config/audit.conf";
    IDTrustConfiguration idtrustConfig = new IDTrustConfiguration();
    idtrustConfig.config(configFile);
    //Get the AuthenticationManager from the SecurityFactory
    AuthenticationManager am =
       SecurityFactory.getAuthenticationManager(securityDomainName);
    assertNotNull(am);
         
    Subject subject = new Subject();
    Principal principal = getPrincipal("anil");
    Object credential = new String("pass");
          
    boolean result = am.isValid(principal, credential, subject);
    assertTrue("Valid Auth", result);
    assertTrue("Subject has principals", !subject.getPrincipals().isEmpty());
         
    Map<String,Object> contextMap = new HashMap<String,Object>();
    
    //Create an audit event indicating success
    AuditEvent auditEvent = new AuditEvent(AuditLevel.SUCCESS,contextMap);
    
    //Get the audit manager from the SecurityFactory
    AuditManager auditManager =
       SecurityFactory.getAuditManager(securityDomainName);
    
    //Now audit the event
    auditManager.audit(auditEvent);
    

     

    The audit.conf configuration file would look as follows:

    <?xml version='1.0'?> 
     
    <policy xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
             xsi:schemaLocation="urn:jboss:security-config:5.0"
             xmlns="urn:jboss:security-config:5.0"
             xmlns:jbxb="urn:jboss:security-config:5.0">
       <application-policy name = "test"> 
           <authentication>
              <login-module code =
       "org.jboss.security.auth.spi.UsersRolesLoginModule"
                 flag = "required">  
              </login-module> 
           </authentication>
           <audit>
              <provider-module code=
          "org.jboss.security.audit.providers.LogAuditProvider"/>
           </audit> 
        </application-policy>  
    </policy>
    

     

    Advantages

    If you develop on IDTrust, then you should be able to move seamlessly into JBoss AS5 where the dependent security libraries are available. You will just need the IDTrust jar.

     

    TBD

    Migration of IDTrust applications to JBoss4.x.  JBoss security team needs to work further on the dependent libraries that are suitable for JBoss4x.

     

    Frequently Asked Questions

     

    1. I am seeing an NoClassDefFound Error (NCDF) or ClassNotFoundException (CNFE) involving org.jboss.logging package.

    Try grabbing the following jars if running in a standalone environment. The jar is not needed for JBAS.

    http://repository.jboss.org/maven2/org/jboss/jboss-common-core/2.2.11.GA/jboss-common-core-2.2.11.GA.jar

    http://repository.jboss.org/maven2/org/jboss/logging/jboss-logging-spi/2.0.5.GA/jboss-logging-spi-2.0.5.GA.jar

     

    2. Can you make it easier to integrate in a standalone environment or a JBAS environment?

    Yes, we are planning to get IDTrust in 3 flavors - Apache Tomcat Version (Standalone), JBoss AS 4.2.x Version and JBoss AS5.x to handle the dependencies better and provide you one zip for each of these runtime environment.

     

     

     

    User Forum: http://www.jboss.org/index.html?module=bb&op=viewforum&f=49