Hello World

A "Hello World!" program is available to test your JAAS installation.

Retrieve File

Download the HelloWorld.tar file for your platform from the samples page to your test directory. Extract the file, for example by using tar -xvf HelloWorld.tar.

You should verify the contents of your test directory.

source files
  • HWLoginModule.java
  • HWPrincipal.java
  • HelloWorld.java
policy files
  • jaas.config
  • java2.policy
  • jaas.policy

Compile Source Files

Note: The example uses Windows-style file separators (\). Unix users should substitute forward slashes (/) in the example.

The three source files, HWLoginModule.java, HWPrincipal.java and HelloWorld.java, are already compiled and therefore do not need to be compiled.

If any of the source files are modified, then change to the test directory that they were saved to and enter:

javac -d .\classes *.java
The classpath should need the classes directory (.\classes) added to it to compile the classes.
Note: HWLoginModule and HWPrincipal are in the com.ibm.security package and will be created in the appropriate directory during compilation ( < test_dir > \classes\com\ibm\security).

Examine Policy Files

The configuration file, jaas.config, contains one entry:

helloWorld {
   com.ibm.security.HWLoginModule required debug=true;
};
Only one LoginModule is supplied with the test case. When executing the HelloWorld application, please experiment by changing the LoginModuleControlFlag (required, requisite, sufficient, optional) and deleting the debug flag. If more LoginModules are available for testing, then feel free to alter this configuration and experiment with multiple LoginModules. HWLoginModule will be discussed shortly.

The Java™ 2 policy file, java2.policy, contains one permission block:

grant {
   permission javax.security.auth.AuthPermission "createLoginContext";
   permission javax.security.auth.AuthPermission "modifyPrincipals";
   permission javax.security.auth.AuthPermission "doAsPrivileged";
};
The three permissions are required because the HelloWorld application (1) creates a LoginContext object, (2) modifies the Principals of the authenticated Subject and (3) calls the doAsPrivileged method of the Subject class.

The JAAS policy file, jaas.policy, also contains one permission block:

grant Principal com.ibm.security.HWPrincipal "bob" {
   permission java.util.PropertyPermission "java.home", "read";
   permission java.util.PropertyPermission "user.home", "read";
   permission java.io.FilePermission "foo.txt", "read";
};

The three permissions are initially granted to an HWPrincipal named bob. The actual Principal added to the authenticated Subject is the username used during the login process (more later). Here's the action code from HelloWorld with the three system calls (the reason for the required permissions) in bold:

   Subject.doAsPrivileged(lc.getSubject(), new PrivilegedAction() {
       public Object run() {
           System.out.println("\nYour java.home property: "
                                   +System.getProperty("java.home"));

           System.out.println("\nYour user.home property: "
                                   +System.getProperty("user.home"));

           File f = new File("foo.txt");
           System.out.print("\nfoo.txt does ");
           if (!f.exists()) System.out.print("not ");
           System.out.println("exist in your current directory");

           System.out.println("\nOh, by the way ...");

           try {
               Thread.currentThread().sleep(2000);
           } catch (Exception e) {
               // ignore
           }
           System.out.println("\n\nHello World!\n");
           return null;
       }
   }, null);
When executing the HelloWorld program, use various usernames and alter jaas.policy accordingly. There should not be a need to alter java2.policy. Also, create a file called foo.txt in the test directory to test the last system call.

Examine Source Files

The LoginModule, HWLoginModule, simply authenticates any user who enters the correct password (case sensitive):

The HelloWorld application permits users three attempts to do so. When Go JAAS is correctly entered, an HWPrincipal with a name equal the username is added to the authenticated Subject.

The Principal class, HWPrincipal, represents a Principal based on the username entered. It is this name that is important when granting permissions to authenticated Subjects.

The main application, HelloWorld, first creates a LoginContext based on a configuration entry with the name helloWorld. The configuration file has already been discussed. Callbacks are used to retrieve user input. Look at the MyCallbackHandler class located in the HelloWorld.java file to see this process.

   LoginContext lc = null;
   try {
       lc = new LoginContext("helloWorld", new MyCallbackHandler());
   } catch (LoginException le) {
       le.printStackTrace();
       System.exit(-1);
   }
The user enters a username/password (up to three times) and if Go JAAS is entered as the password, then the Subject is authenticated (HWLoginModule adds a HWPrincipal to the Subject).

As mentioned previously, work is then performed as the authenticated Subject.

Run HelloWorld Test

To run the HelloWorld program, first change to the test directory. The configuration and policy files will need to be loaded. See Implementation for the correct properties to set either in java.security or on the command line. The latter method will be discussed here.

The following command has been broken up into several lines for clarity. Enter as one continuous command.

java -Djava.security.manager=
     -Djava.security.auth.login.config=.\jaas.config
     -Djava.security.policy=.\java2.policy
     -Djava.security.auth.policy=.\jaas.policy
     HelloWorld
Note: The use of .\filename for the policy files is necessary because each user's test directory canonical path will vary. If desired, substitute "." with the path to the test directory. For example, if the test directory is c:\test\hello, then the first file would be changed to:
-Djava.security.auth.login.config=c:\test\hello\jaas.config
If the policy files are not found, a SecurityException will be thrown. Otherwise, information concerning your java.home and user.home properties will be displayed. Also, the existence of a file called foo.txt in your test directory will be checked. Finally, the ubiquitous "Hello World" message is displayed.

Having Fun With HelloWorld

Rerun HelloWorld as many times as you like. It has already been suggested to vary the username/passwords entered, change the configuration file entries, change the policy file permissions, and to even add (stack) additional LoginModules to the helloWorld configuration entry. You could add codebase fields to the policy files too.

Finally, try running the program without a SecurityManager to see how it works if you run into problems.