JAAS Authorization

This tutorial expands the program and policy file developed intheJAAS Authentication tutorial todemonstrate the JAAS authorization component, which ensures theauthenticated caller has the access control rights (permissions)required to do subsequent security-sensitive operations. Sincethe authorization component requires that the user authenticationfirst be completed, please read theJAASAuthentication tutorial first if you have not already doneso.

The rest of this tutorial consists of the followingsections:

If you want to first see the tutorial code in action, you canskip directly toRunning the AuthorizationTutorial Code and then go back to the other sections to learnmore.

What is JAASAuthorization?

JAAS authorization extends the existing Java securityarchitecture that uses a securitypolicy to specify what access rightsare granted to executing code. That architecture, introduced inthe Java 2 platform, iscode-centric. That is, thepermissions are granted based on code characteristics: where thecode is coming from and whether it is digitally signed and if soby whom. We saw an example of this in thejaasacn.policy file used in theJAAS Authentication tutorial. That filecontains the following:

grant codebase "file:./JaasAcn.jar" {   permission javax.security.auth.AuthPermission                     "createLoginContext.JaasSample";};

This grants the code in theJaasAcn.jar file,located in the current directory, the specified permission. (Nosigner is specified, so it doesn't matter whether the code issigned or not.)

JAAS authorization augments the existing code-centric accesscontrols with newuser-centric access controls.Permissions can be granted based not just on what code is runningbut also onwho is running it.

When an application uses JAAS authentication to authenticatethe user (or other entity such as a service), aSubjectis created as a result. The purpose of the Subject is torepresent the authenticated user. A Subject is comprised of a setofPrincipals,where each Principal represents an identity for that user. Forexample, a Subject could have a name Principal ("Susan Smith")and a Social Security Number Principal ("987-65-4321"), therebydistinguishing this Subject from other Subjects.

Permissions can be granted in the policy to specificPrincipals. After the user has been authenticated, theapplication can associate the Subject with the current accesscontrol context. For each subsequent security-checked operation,(a local file access, for example), the Java runtime willautomatically determine whether the policy grants the requiredpermission only to a specific Principal and if so, the operationwill be allowed only if the Subject associated with the accesscontrol context contains the designated Principal.

How is JAASAuthorization Performed?

To make JAAS authorization take place, the following isrequired:

The user must be authenticated, as described in theJAAS Authentication tutorial.
Principal-based entries must beconfigured in the security policy.
The Subject that is the result of authentication must beassociated with the current accesscontrol context.

How Do You MakePrincipal-Based Policy File Statements?

Policy filegrant statements can now optionally include one ormore Principal fields. Inclusion of a Principal field indicatesthat the user or other entity represented by the specifiedPrincipal, executing the specified code, has the designatedpermissions.

Thus, the basic format of agrant statement isnow

grant <signer(s) field>, <codeBase URL>   <Principal field(s)> {    permissionperm_class_name "target_name", "action";    ....    permissionperm_class_name "target_name", "action";  };

where each of the signer, codeBase and Principal fields isoptional and the order between the fields doesn't matter.

A Principal field looks like the following:

PrincipalPrincipal_class "principal_name"

That is, it is the word "Principal" (where case doesn'tmatter) followed by the (fully qualified) name of a Principalclass and a principal name.

A Principal class is a class that implements thejava.security.Principalinterface. All Principal objects have an associated name that canbe obtained by calling theirgetName method. Theformat used for the name is dependent on each Principalimplementation.

The type of Principal placed in the Subject created by theKerberos authentication mechanism used by this tutorial isjavax.security.auth.kerberos.KerberosPrincipal, sothat is what should be used as thePrincipal_class part of ourgrant statement's Principal designation. User namesforKerberosPrincipals are of the form "name@realm".Thus, if the user name is "mjones" and the realm is"KRBNT-OPS.ABC.COM", the fullprincipal_namedesignation to use in thegrant statement is"mjones@KRBNT-OPS.ABC.COM".

It is possible to include more than one Principal field in agrant statement. If multiple Principal fields arespecified, then the permissions in thatgrantstatement are granted only if the Subject associated with thecurrent access control context containsall of thosePrincipals.

To grant the same set of permissions to different Principals,create multiplegrant statements where each liststhe permissions and contains a single Principal field designatingone of the Principals.

The policy file for this tutorial includes onegrant statement with a Principal field:

grant codebase "file:./SampleAction.jar",    Principal javax.security.auth.kerberos.KerberosPrincipal         "your_user_name@your_realm"  {   permission java.util.PropertyPermission "java.home", "read";   permission java.util.PropertyPermission "user.home", "read";   permission java.io.FilePermission "foo.txt", "read";};

where you substitute your Kerberos user name (complete with "@"and realm) for "your_user_name@your_realm".

This specifies that the indicated permissions are granted tothe specified principal executing the code inSampleAction.jar.

How Do You Associatea Subject with an Access Control Context?

To create and associate a Subject with an access controlcontext, you need the following:

The user must first be authenticated, as described inJAAS Authentication.
The staticdoAs method from the Subject classmust be called, passing it an authenticated Subject and ajava.security.PrivilegedActionorjava.security.PrivilegedExceptionAction. (SeeAPI for Privileged Blocks for acomparison of PrivilegedAction and PrivilegedExceptionAction.)ThedoAs method associates the provided Subject withthe current access control context and then invokes therun method from the action. Therunmethod implementation contains all the code to be executed as thespecified Subject. The action thus executes as the specifiedSubject.
The staticdoAsPrivileged method from the Subjectclass may be called instead of thedoAs method. Inaddition to the parameters passed todoAs,doAsPrivileged requires a third parameter: anAccessControlContext. UnlikedoAs, which associatesthe provided Subject with the current access control context,doAsPrivileged associates the Subject with theprovided access control context. SeedoAs vs.doAsPrivileged in the JAAS Reference Guide for a comparisonof those methods.

The Authorization TutorialCode

The code for this tutorial consists of two files:

JaasAzn.java is exactly the sameas theJaasAcn.java from theJAAS Authentication tutorial except for theadditional code needed to callSubject.doAsPrivileged.
SampleAction.java containsthe SampleAction class. This class implements PrivilegedActionand has arun method that contains all the code wewant to be executed with Principal-based authorizationchecks.

JaasAzn.java

JaasAzn.java is exactly the same astheJaasAcn.java code used in the previous tutorialexcept with three statements added at the end of themain method, after the authentication is done. Thesestatements result in (1) association of a Subject representingthe authenticated user with the current access control contextand (2) execution of the code in therun method ofSampleAction. Associating the Subject with the access controlcontext enables security-sensitive operations in the SampleActionrun method (and any code it invokes directly orindirectly) to be executed if a Principal representing theauthenticated user is granted the required permissions in thecurrent policy.

LikeJaasAcn.java,JaasAzn.javainstantiates a LoginContextlc and calls itslogin method to perform the authentication. Ifsuccessful, the authenticated Subject (which includes a Principalrepresenting the user) is obtained by calling the LoginContext'sgetSubject method:

Subject mySubject = lc.getSubject();

Themain method then callsSubject.doAsPrivileged, passing it the authenticatedSubjectmySubject, a PrivilegedAction (SampleAction)and anull AccessControlContext, as described in thefollowing.

The SampleAction class is instantiated via the following:

PrivilegedAction action = new SampleAction();

The call toSubject.doAsPrivileged is performedvia:

Subject.doAsPrivileged(mySubject, action, null);

ThedoAsPrivileged method invokes execution oftherun method in the PrivilegedActionaction (SampleAction) to initiate execution of therest of the code, which is considered to be executed on behalf ofthe SubjectmySubject.

Passingnull as the AccessControlContext (third)argument todoAsPrivileged indicates thatmySubject should be associated with a new emptyAccessControlContext. The result is that security checksoccurring during execution of SampleAction will only requirepermissions for the SampleAction code itself (or other code itinvokes), running asmySubject. Note that the callerofdoAsPrivileged (and the callers on the executionstack at the timedoAsPrivileged was called) do notrequire any permissions while the action executes.

SampleAction.java

SampleAction.java contains theSampleAction class. This class implementsjava.security.PrivilegedAction and has arun method that contains all the code we want to beexecuted as the SubjectmySubject. For thistutorial, we will perform three operations, each of which cannotbe done unless code has been granted required permissions. Wewill:

Read and print the value of thejava.home systemproperty,
Read and print the value of theuser.home systemproperty, and
Determine whether or not a file namedfoo.txtexists in the current directory.

Here is the code:

import java.io.File;import java.security.PrivilegedAction;public classSampleAction implements PrivilegedAction {  public Objectrun() {    System.out.println("\nYour java.home property value is: "                + System.getProperty("java.home"));    System.out.println("\nYour user.home property value is: "                + 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 the current working directory.");    return null;  }}

The Login ConfigurationFile

The login configuration file used for this tutorial can beexactly the same as that used by theJAASAuthentication tutorial. Thus we can usejaas.conf, which contains just one entry:

JaasSample {  com.sun.security.auth.module.Krb5LoginModule required;};

This entry is named "JaasSample" and that is the name thatboth our tutorial applicationsJaasAcn andJaasAzn use to refer to it. The entry specifies thatthe LoginModule to be used to do the user authentication is theKrb5LoginModule in thecom.sun.security.auth.modulepackage and that this Krb5LoginModule is required to "succeed" inorder for authentication to be considered successful. TheKrb5LoginModule succeeds only if the name and password suppliedby the user are successfully used to log the user into theKerberos KDC.

The Policy File

This authorization tutorial contains two classes,JaasAzn andSampleAction. The code ineach class contains some security-sensitive operations and thusrelevant permissions are required in a policy file in order forthe operations to be executed.

Permissions Required by JaasAzn

The main method of theJaasAzn class does twooperations for which permissions are required. It

creates a LoginContext, and
calls thedoAsPrivileged static method of theSubject class.

The LoginContext creation is exactly the same as was done inthe authentication tutorial, and it thus needs the samejavax.security.auth.AuthPermission permission withtarget "createLoginContext.JaasSample".

In order to call thedoAsPrivileged method of theSubject class, you need to have ajavax.security.auth.AuthPermission with target"doAsPrivileged".

Assuming theJaasAzn class is placed in a JARfile namedJaasAzn.jar, these permissions can begranted to theJaasAzn code via the followinggrant statement in the policy file:

grant codebase "file:./JaasAzn.jar" {   permission javax.security.auth.AuthPermission                     "createLoginContext.JaasSample";   permission javax.security.auth.AuthPermission "doAsPrivileged";};

Permissions Required by SampleAction

TheSampleAction code does three operations forwhich permissions are required. It

reads the value of the "java.home" system property.
reads the value of the "user.home" system property.
checks to see whether or not a file namedfoo.txt exists in the current directory.

The permissions required for these operations are thefollowing:

permission java.util.PropertyPermission "java.home", "read";permission java.util.PropertyPermission "user.home", "read";permission java.io.FilePermission "foo.txt", "read";

We need to grant these permissions to the code inSampleAction.class, which we will place in a JARfile namedSampleAction.jar. However, for thisparticulargrant statement we want to grant thepermissions not just to thecode but to a specific userexecuting the code, to demonstrate how to restrict access to aparticular user.

Thus, as explained inHow Do You MakePrincipal-Based Policy File Statements?, ourgrant statement looks like the following:

grant codebase "file:./SampleAction.jar",    Principal javax.security.auth.kerberos.KerberosPrincipal         "your_user_name@your_realm"  {   permission java.util.PropertyPermission "java.home", "read";   permission java.util.PropertyPermission "user.home", "read";   permission java.io.FilePermission "foo.txt", "read";};

You substitute your Kerberos user name (complete with "@" andrealm) for "your_user_name@your_realm". For example,if your user name is "mjones" and your realm is"KRBNT-OPERATIONS.ABC.COM", you would use"mjones@KRBNT-OPERATIONS.ABC.COM" (complete with the quotes).

The Full Policy File

The full policy file isjaasazn.policy.

Running the AuthorizationTutorial Code

To execute our JAAS authorization tutorial code, all you haveto do is

Place the following files into a directory:
- TheJaasAzn.java source file.
- TheSampleAction.java sourcefile.
- Thejaas.conf login configurationfile.
- Thejaasazn.policy policyfile.
Replace "your_user_name@your_realm" injaasazn.policy with your user name and realm.
CompileSampleAction.java andJaasAzn.java:
```
javac SampleAction.java JaasAzn.java
```
Create a JAR file namedJaasAzn.jar containingJaasAzn.class:
```
jar -cvf JaasAzn.jar JaasAzn.class
```
Create a JAR file namedSampleAction.jarcontainingSampleAction.class:
```
jar -cvf SampleAction.jar SampleAction.class
```
Execute theJaasAzn application, specifying
1. by an appropriate-classpath clause that classesshould be searched for in theJaasAzn.jar andSampleAction.jar JAR files,
2. by-Djava.security.manager that a securitymanager should be installed,
3. by-Djava.security.krb5.realm=<your_realm>that your Kerberos realm is the one specified.
4. by-Djava.security.krb5.kdc=<your_kdc>that your Kerberos KDC is the one specified.
5. by-Djava.security.policy=jaasazn.policy thatthe policy file to be used isjaasazn.policy,and
6. by-Djava.security.auth.login.config=jaas.confthat the login configuration file to be used isjaas.conf.
Below are the full commands to use for both Microsoft Windowsand Unix systems. The only difference is that on Windows systemsyou use semicolons to separate classpath items, while you usecolons for that purpose on Unix systems.Be sure to replace<your_realm> with your Kerberos realm, and<your_kdc> with your Kerberos KDC.
Here is the full command for Windows systems:
```
java -classpath JaasAzn.jar;SampleAction.jar  -Djava.security.manager  -Djava.security.krb5.realm=<your_realm>  -Djava.security.krb5.kdc=<your_kdc>  -Djava.security.policy=jaasazn.policy  -Djava.security.auth.login.config=jaas.conf JaasAzn
```
Here is the full command for UNIX systems:
```
java -classpath JaasAzn.jar:SampleAction.jar  -Djava.security.manager  -Djava.security.krb5.realm=<your_realm>  -Djava.security.krb5.kdc=<your_kdc>  -Djava.security.policy=jaasazn.policy  -Djava.security.auth.login.config=jaas.conf JaasAzn
```
Type the full command on one line. Multiple lines are usedhere for legibility. If the command is too long for your system,you may need to place it in a .bat file (for Windows) or a .shfile (for UNIX) and then run that file to execute thecommand.
You will be prompted for your Kerberos user name and password,and the underlying Kerberos authentication mechanism specified inthe login configuration file will log you into Kerberos. If yourlogin is successful, you will see the message "Authenticationsucceeded!" and if not, you will see "Authentication Failed."
For login troubleshooting suggestions, seeTroubleshooting.
Once authentication is successfully completed, the rest of theprogram (inSampleAction) will be executed on behalfof you, the user, requiring you to have been granted appropriatepermissions. Thejaasazn.policy policy file grantsyou the required permissions, so you will see a display of thevalues of yourjava.home anduser.homesystem properties and a statement as to whether or not you have afile namedfoo.txt in the current directory.

Movatterモバイル変換

JAAS Authorization

JaasAzn.java

Permissions Required by JaasAzn

Permissions Required by SampleAction

The Full Policy File