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:
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).
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.
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
Comments