Details: How HelloWorld for Java Authentication and Authorization Service works

This document takes a closer look at how HelloWorld for Java™ Authentication and Authorization Service (JAAS) works. This information should be considered a replacement for the HelloWorld section of the API Developers Guide. The source code, policy, and configuration files are the same as those in the API Developers Guide. There are, however, some aspects that are unique to the iSeries™ server.

Note: By using the code examples, you agree to the terms of the Code license and disclaimer information.

Configuration and policy files

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

helloWorld {
    com.ibm.security.HWLoginModule required debug=true;
};

The test case includes only one LoginModule. When running the HelloWorld application, you can experiment by changing the LoginModuleControlFlag (required, requisite, sufficient, optional) and deleting the debug flag. If more LoginModules are available for testing, then you can alter this configuration and experiment with multiple LoginModules.

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 does the following:

  1. Creates a LoginContext object.
  2. Changes the Principals of the the authenticated Subject.
  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 user name used during the login process.

Here is 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 running the HelloWorld program, use various user names 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 and confirm that the correct level of access is granted to that file.

Examine HelloWorld source files

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

If running with a security manager, you must enter user 'bob' for all of the access permissions to succeed.

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

The Principal class, HWPrincipal, represents a Principal based on the user name that is entered. This name 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. Callbacks are used to retrieve user input. Look at the MyCallbackHandler class located in the HelloWorld.java file to see this process. Here is an excerpt from the source code:

         LoginContext lc = null;
         try {
             lc = new LoginContext("helloWorld", new MyCallbackHandler());
         } catch (LoginException le) {
             le.printStackTrace();
             System.exit(-1);
         }

The user enters a user name and 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). Work is then performed as the authenticated Subject.

If the policy files are not found, a SecurityException is thrown. Otherwise, information concerning your java.home and user.home properties is displayed. Also, the existence of a file called foo.txt in your test directory is checked. Finally, the ubiquitous "Hello World" message is displayed.

Having fun with HelloWorld

Rerun HelloWorld as many times as you like. Here is a list of some of the things that you might want to try:

Parent topic: Compile and run HelloWorld with Java Authentication and Authorization Service on an iSeries server