Oracle Technology Network Software Downloads Documentation Search

JavaTM Authentication and Authorization Service (JAAS)

Reference Guide
for the Java TM SE Development Kit 6

Introduction
Who Should Read This Document
Related Documentation

Core Classes and Interfaces

Common Classes
Subject
Principals
Credentials
Authentication Classes and Interfaces
LoginContext
LoginModule
CallbackHandler
Callback
Authorization Classes
Policy
AuthPermission
PrivateCredentialPermission

JAAS Tutorials and Sample Programs

Appendix A: JAAS Settings in the java.security Security Properties File

Appendix B: Example Login Configurations

Introduction
Demo Version - ExpertPDF Software Components
The JavaT M Authentication and Authorization Service (JAAS) was introduced as an optional package (extension) to the JavaT M 2 SDK, Standard Edition (J2SDK), v 1.3.
JAAS was integrated into the J2SDK 1.4.

JAAS can be used for two purposes:

for authentication of users, to reliably and securely determine who is currently executing Java code, regardless of whether the code is running as an application, an
applet, a bean, or a servlet; and
for authorization of users to ensure they have the access control rights (permissions) required to do the actions performed.

JAAS implements a Java version of the standard Pluggable Authentication Module (PAM) framework. See Making Login Services Independent from Authentication
Technologies for further information.

Traditionally Java has provided codesource-based access controls (access controls based on where the code originated from and who signed the code). It lacked,
however, the ability to additionally enforce access controls based on who runs the code. JAAS provides a framework that augments the Java security architecture with such
support.

JAAS authentication is performed in a pluggable fashion. This permits applications to remain independent from underlying authentication technologies. New or updated
authentication technologies can be plugged under an application without requiring modifications to the application itself. Applications enable the authentication process
by instantiating a L o g i n C o n t e x t object, which in turn references a C o n f i g u r a t i o n to determine the authentication technology(ies), or L o g i n M o d u l e(s), to be
used in performing the authentication. Typical L o g i n M o d u l es may prompt for and verify a username and password. Others may read and verify a voice or fingerprint
sample.

Once the user or service executing the code has been authenticated, the JAAS authorization component works in conjunction with the core Java SE access control model
to protect access to sensitive resources. Unlike in the J2SDK 1.3 and earlier, where access control decisions are based solely on code location and code signers (a
C o d e S o u r c e), in the J2SDK 1.4 access control decisions are based both on the executing code's C o d e S o u r c e and on the user or service running the code, who is
represented by a S u b j e c t object. The S u b j e c t is updated by a L o g i n M o d u l e with relevant P r i n c i p a ls and credentials if authentication succeeds.

Who Should Read This Document

This document is intended for experienced developers who require the ability to design applications constrained by a C o d e S o u r c e-based and
S u b j e c t-based security model. It is also intended to be read by LoginModule developers (developers implementing an authentication technology) prior to
reading the JAAS LoginModule Developer's Guide.

You may wish to first read the JAAS Authentication and JAAS Authorization tutorials to get an overview of how to use JAAS and to see sample code in action,
and then return to this document for further information.

Related Documentation

This document assumes you have already read the following:

Java SE Security Architecture

Sample footer: http://download.oracle.com/javase/7/docs/technotes/guides/security/jaas/JAASRefGuide.html. You can change color, font and other options Page 1 / 10
 JAAS white paper
Java SE Security Tutorial

A supplement to this guide is the JAAS LoginModule Developer's Guide, intended for experienced programmers who require the ability to write a
L o g i n M o d u l e implementing an authentication technology.

If you wish to learn more about the standard Pluggable Authentication Module (PAM) framework (JAAS implements a Java version of PAM), see Making
Login Services Independent from Authentication Technologies.

The following tutorials for JAAS authentication and authorization can be run by everyone:

JAAS Authentication Tutorial

JAAS Authorization Tutorial

Similar tutorials for JAAS authentication and authorization, but which demonstrate the use of a Kerberos LoginModule and thus which require a Kerberos
installation, can be found at

JAAS Authentication
JAAS Authorization

These two tutorials are a part of the Java GSS-API and JAAS sequence of tutorials that utilize Kerberos as the underlying technology for authentication and
secure communication.

Core Classes and Interfaces

The JAAS-related core classes and interfaces can be broken into three categories: Common, Authentication, and Authorization.

Common Classes
Subject, Principal, Credential (actually, any Object)
Authentication Classes and Interfaces
LoginContext, LoginModule, CallbackHandler, Callback
Authorization Classes
Policy, AuthPermission, PrivateCredentialPermission

Common Classes

Common classes are those shared by both the JAAS authentication and authorization components.
The key JAAS class is j a v a x . s e c u r i t y . a u t h . S u b j e c t, which represents a grouping of related information for a single entity such as a person. It
encompasses the entity's Principals, public credentials, and private credentials.

Note that the j a v a . s e c u r i t y . P r i n c i p a l interface is used to represent a Principal. Also note that a credential, as defined by JAAS, may be any
Object.
Demo Version - ExpertPDF Software Components
Subject

To authorize access to resources, applications first need to authenticate the source of the request. The JAAS framework defines the term
subject to represent the source of a request. A subject may be any entity, such as a person or a service. Once the subject is authenticated, a
j a v a x . s e c u r i t y . a u t h . S u b j e c t is populated with associated identities, or P r i n c i p a ls. A S u b j e c t may have many
P r i n c i p a ls. For example, a person may have a name P r i n c i p a l ("John Doe") and a SSN P r i n c i p a l ("123-45-6789"), which
distinguish it from other subjects.
A S u b j e c t may also own security-related attributes, which are referred to as credentials. Sensitive credentials that require special
protection, such as private cryptographic keys, are stored within a private credential S e t. Credentials intended to be shared, such as public
key certificates, are stored within a public credential S e t. Different permissions (described below) are required to access and modify the
different credential S e ts.

Subjects are created using these constructors:

public Subject();

public Subject(boolean readOnly, Set principals,

Set pubCredentials, Set privCredentials);

The first constructor creates a S u b j e c t with empty (non-null) S e ts of P r i n c i p a ls and credentials. The second constructor creates a
S u b j e c t with the specified S e ts of P r i n c i p a ls and credentials. It also has a boolean argument which can be used to make the
S u b j e c t read-only. In a read-only S u b j e c t, the P r i n c i p a l and credential S e ts are immutable.
An application writer does not have to instantiate a S u b j e c t. If the application instantiates a L o g i n C o n t e x t and does not pass a
S u b j e c t to the L o g i n C o n t e x t constructor, the L o g i n C o n t e x t instantiates a new empty S u b j e c t. See the LoginContext section.

If a S u b j e c t was not instantiated to be in a read-only state, it can be set read-only by calling the following method:

public void setReadOnly();

A j a v a x . s e c u r i t y . a u t h . A u t h P e r m i s s i o n with target "setReadOnly" is required to invoke this method. Once in a read-only state,
any attempt to add or remove P r i n c i p a ls or credentials will result in an I l l e g a l S t a t e E x c e p t i o n being thrown.
The following method may be called to test a S u b j e c t's read-only state:

public boolean isReadOnly();

To retrieve the P r i n c i p a ls associated with a Subject, two methods are available:

public Set getPrincipals();

public Set getPrincipals(Class c);

Sample footer: http://download.oracle.com/javase/7/docs/technotes/guides/security/jaas/JAASRefGuide.html. You can change color, font and other options Page 2 / 10
 The first method returns all P r i n c i p a ls contained in the S u b j e c t, while the second method only returns those P r i n c i p a ls that are
an instance of the specified Class c , or an instance of a subclass of Class c . An empty set will be returned if the S u b j e c t does not have
any associated P r i n c i p a ls.

To retrieve the public credentials associated with a S u b j e c t, these methods are available:

public Set getPublicCredentials();

public Set getPublicCredentials(Class c);

The behavior of these methods is similar to that for the g e t P r i n c i p a l s methods, except in this case the public credentials are being
obtained.

To access private credentials associated with a S u b j e c t, the following methods are available:

public Set getPrivateCredentials();

public Set getPrivateCredentials(Class c);

The behavior of these methods is similar to that for the g e t P r i n c i p a l s and g e t P u b l i c C r e d e n t i a l s methods.

To modify or operate upon a S u b j e c t's P r i n c i p a l S e t, public credential S e t, or private credential S e t, callers use the methods
defined in the j a v a . u t i l . S e t class. The following example demonstrates this:

Subject subject;
Principal principal;
Object credential;

. . .

// add a Principal and credential to the Subject

subject.getPrincipals().add(principal);
subject.getPublicCredentials().add(credential);

Note: An A u t h P e r m i s s i o n with target "modifyPrincipals", "modifyPublicCredentials", or "modifyPrivateCredentials" is required to modify

the respective S e ts. Also note that only the sets returned via the g e t P r i n c i p a l s ( ), g e t P u b l i c C r e d e n t i a l s ( ), and
g e t P r i v a t e C r e d e n t i a l s ( ) methods with no arguments are backed by the S u b j e c t's respective internal sets. Therefore any
modification to the returned set affects the internal sets as well. The sets returned via the g e t P r i n c i p a l s ( C l a s s c ),
g e t P u b l i c C r e d e n t i a l s ( C l a s s c ), and g e t P r i v a t e C r e d e n t i a l s ( C l a s s c ) methods are not backed by the S u b j e c t's
respective internal sets. A new set is created and returned for each such method invocation. Modifications to these sets will not affect the
S u b j e c t's internal sets.

In order to iterate through a Set of private credentials, you need a j a v a x . s e c u r i t y . a u t h . P r i v a t e C r e d e n t i a l P e r m i s s i o n to

access each credential. See the P r i v a t e C r e d e n t i a l P e r m i s s i o n API documentation for further information.

A S u b j e c t may be associated with an A c c e s s C o n t r o l C o n t e x t (see the d o A s and d o A s P r i v i l e g e d method descriptions below).

The following method returns the S u b j e c t associated with the specified A c c e s s C o n t r o l C o n t e x t, or n u l l if no S u b j e c t is
Demo Version - ExpertPDF Software Components
associated with the specified A c c e s s C o n t r o l C o n t e x t.

public static Subject getSubject(final AccessControlContext acc);

An A u t h P e r m i s s i o n with target "getSubject" is required to call S u b j e c t . g e t S u b j e c t.

The S u b j e c t class also includes the following methods inherited from j a v a . l a n g . O b j e c t.

public boolean equals(Object o);

public String toString();
public int hashCode();

The doAs methods for performing an action as a particular Subject

The following static methods may be called to perform an action as a particular S u b j e c t:

public static Object

doAs(final Subject subject,
final java.security.PrivilegedAction action);

public static Object

doAs(final Subject subject,
final java.security.PrivilegedExceptionAction action)
throws java.security.PrivilegedActionException;

Both methods first associate the specified s u b j e c t with the current Thread's A c c e s s C o n t r o l C o n t e x t, and then
execute the a c t i o n. This achieves the effect of having the a c t i o n run as the s u b j e c t. The first method can throw runtime
exceptions but normal execution has it returning an Object from the r u n method of its a c t i o n argument. The second
method behaves similarly except that it can throw a checked exception from its P r i v i l e g e d E x c e p t i o n A c t i o n r u n
method. An A u t h P e r m i s s i o n with target "doAs" is required to call the d o A s methods.

Subject.doAs Example

Here is an example utilizing the first d o A s method. Assume that someone named "Bob" has been authenticated by a
L o g i n C o n t e x t (see the LoginContext section) and as a result a S u b j e c t was populated with a P r i n c i p a l of class
c o m . i b m . s e c u r i t y . P r i n c i p a l, and that P r i n c i p a l has the name "BOB". Also assume that a SecurityManager has
been installed, and that the following exists in the access control policy (see the Policy section for more details on the policy
file).

// grant "BOB" permission to read the file "foo.txt"

grant Principal com.ibm.security.Principal "BOB" {
permission java.io.FilePermission "foo.txt", "read";

Sample footer: http://download.oracle.com/javase/7/docs/technotes/guides/security/jaas/JAASRefGuide.html. You can change color, font and other options Page 3 / 10
 } ;

Here is the sample application code:

class ExampleAction implements java.security.PrivilegedAction {

public Object run() {
java.io.File f = new java.io.File("foo.txt");

// the following call invokes a security check

if (f.exists()) {
System.out.println("File foo.txt exists");
}
return null;
}
}

public class Example1 {

public static void main(String[] args) {

// Authenticate the subject, "BOB".

// This process is described in the
/ / LoginContext s e c t i o n .

Subject bob;
// Set bob to the Subject created during the
// authentication process

// perform "ExampleAction" as "BOB"

Subject.doAs(bob, new ExampleAction());
}
}

During execution, E x a m p l e A c t i o n will encounter a security check when it makes a call to f . e x i s t s ( ). However, since
E x a m p l e A c t i o n is running as "BOB", and the policy (above) grants the necessary F i l e P e r m i s s i o n to "BOB", the
E x a m p l e A c t i o n will pass the security check. If the g r a n t statement in the policy is altered (adding an incorrect
CodeBase or changing the P r i n c i p a l to "MOE", for example), then a S e c u r i t y E x c e p t i o n will be thrown.

The doAsPrivileged methods

The following methods also perform an action as a particular S u b j e c t.

public static Object doAsPrivileged(

final Subject subject,
final java.security.PrivilegedAction action,
final java.security.AccessControlContext acc);

Demo
p u b l i c Version
s t a t i c O b j e c- t ExpertPDF
d o A s P r i v i l e g e d (Software Components
final Subject subject,
final java.security.PrivilegedExceptionAction action,
final java.security.AccessControlContext acc)
throws java.security.PrivilegedActionException;

An A u t h P e r m i s s i o n with target "doAsPrivileged" is required to call the d o A s P r i v i l e g e d methods.

doAs vs. doAsPrivileged

The d o A s P r i v i l e g e d methods behave exactly the same as the d o A s methods, except that instead of associating the
provided S u b j e c t with the current Thread's A c c e s s C o n t r o l C o n t e x t, they use the provided
A c c e s s C o n t r o l C o n t e x t. In this way, actions can be restricted by A c c e s s C o n t r o l C o n t e x ts different from the current
one.

An A c c e s s C o n t r o l C o n t e x t contains information about all the code executed since the A c c e s s C o n t r o l C o n t e x t

was instantiated, including the code location and the permissions the code is granted by the policy. In order for an access
control check to succeed, the policy must grant each code item referenced by the A c c e s s C o n t r o l C o n t e x t the required
permissions.

If the A c c e s s C o n t r o l C o n t e x t provided to d o A s P r i v i l e g e d is n u l l, then the action is not restricted by a separate

A c c e s s C o n t r o l C o n t e x t. One example where this may be useful is in a server environment. A server may authenticate
multiple incoming requests and perform a separate d o A s operation for each request. To start each d o A s action "fresh," and
without the restrictions of the current server A c c e s s C o n t r o l C o n t e x t, the server can call d o A s P r i v i l e g e d and pass
in a n u l l A c c e s s C o n t r o l C o n t e x t.

Principals

As mentioned previously, P r i n c i p a ls may be associated with a S u b j e c t if authentication is successful. P r i n c i p a ls represent

S u b j e c t identities, and must implement the j a v a . s e c u r i t y . P r i n c i p a l and j a v a . i o . S e r i a l i z a b l e interfaces. The Subject
section describes ways to update the P r i n c i p a ls associated with a S u b j e c t.

Credentials

Public and private credential classes are not part of the core JAAS class library. Any class can represent a credential. Developers, however,
may elect to have their credential classes implement two interfaces related to credentials: R e f r e s h a b l e and D e s t r o y a b l e.
Refreshable

The j a v a x . s e c u r i t y . a u t h . R e f r e s h a b l e interface provides the capability for a credential to refresh itself. For
example, a credential with a particular time-restricted lifespan may implement this interface to allow callers to refresh the time
period for which it is valid. The interface has two abstract methods:

Sample footer: http://download.oracle.com/javase/7/docs/technotes/guides/security/jaas/JAASRefGuide.html. You can change color, font and other options Page 4 / 10
 boolean isCurrent();

This method determines whether the credential is current or valid.

void refresh() throws RefreshFailedException;

This method updates or extends the validity of the credential. The method implementation should perform an
A u t h P e r m i s s i o n ( " r e f r e s h C r e d e n t i a l " ) security check to ensure the caller has permission to refresh the
credential.

Destroyable

The j a v a x . s e c u r i t y . a u t h . D e s t r o y a b l e interface provides the capability of destroying the contents within a

credential. The interface has two abstract methods:

boolean isDestroyed();

Determines whether the credential has been destroyed.

void destroy() throws DestroyFailedException;

Destroys and clears the information associated with this credential. Subsequent calls to certain methods on this credential
will result in an I l l e g a l S t a t e E x c e p t i o n being thrown. The method implementation should perform an
A u t h P e r m i s s i o n ( " d e s t r o y C r e d e n t i a l " ) security check to ensure the caller has permission to destroy the
credential.

Authentication Classes and Interfaces

To authenticate a subject (user or service), the following steps are performed:

1. An application instantiates a L o g i n C o n t e x t.
2. The L o g i n C o n t e x t consults a C o n f i g u r a t i o n to load all of the L o g i n M o d u l es configured for that application.
3. The application invokes the L o g i n C o n t e x t's l o g i n method.
4. The l o g i n method invokes all of the loaded L o g i n M o d u l es. Each L o g i n M o d u l e attempts to authenticate the subject. Upon
success, L o g i n M o d u l es associate relevant P r i n c i p a ls and credentials with a S u b j e c t object that represents the subject being
authenticated.
5. The L o g i n C o n t e x t returns the authentication status to the application.
6. If authentication succeeded, the application retrieves the S u b j e c t from the L o g i n C o n t e x t.

The authentication classes are described below.

LoginContext
Demo Version - ExpertPDF Software Components
The j a v a x . s e c u r i t y . a u t h . l o g i n . L o g i n C o n t e x t class provides the basic methods used to authenticate subjects,
and provides a way to develop an application independent of the underlying authentication technology. The L o g i n C o n t e x t
consults a C o n f i g u r a t i o n to determine the authentication services, or L o g i n M o d u l e(s), configured for a particular
application. Therefore, different L o g i n M o d u l es can be plugged in under an application without requiring any modifications
to the application itself.

L o g i n C o n t e x t offers four constructors from which to choose:

public LoginContext(String name) throws LoginException;

public LoginContext(String name, Subject subject) throws LoginException;

public LoginContext(String name, CallbackHandler callbackHandler)

throws LoginException

public LoginContext(String name, Subject subject,

CallbackHandler callbackHandler) throws LoginException

All of the constructors share a common parameter: name. This argument is used by the L o g i n C o n t e x t as an index into
the login Configuration to determine which L o g i n M o d u l es are configured for the application instantiating the
L o g i n C o n t e x t. Constructors that do not take a S u b j e c t as an input parameter instantiate a new S u b j e c t. Null inputs
are disallowed for all constructors. Callers require an A u t h P e r m i s s i o n with target "createLoginContext.<name>" to
instantiate a L o g i n C o n t e x t. Here, <name> refers to the name of the login configuration entry that the application
references in the name parameter for the L o g i n C o n t e x t instantiation.
See the CallbackHandler section for information on what a C a l l b a c k H a n d l e r is and when you may need one.

Actual authentication occurs with a call to the following method:

public void login() throws LoginException;

When l o g i n is invoked, all of the configured L o g i n M o d u l es are invoked to perform the authentication. If the authentication
succeeded, the S u b j e c t (which may now hold P r i n c i p a ls, public credentials, and private credentials) can be retrieved
by using the following method:

public Subject getSubject();

To logout a S u b j e c t and remove its authenticated P r i n c i p a l s and credentials, the following method is provided:

public void logout() throws LoginException;

The following code sample demonstrates the calls necessary to authenticate and logout a Subject:

Sample footer: http://download.oracle.com/javase/7/docs/technotes/guides/security/jaas/JAASRefGuide.html. You can change color, font and other options Page 5 / 10
 // let the LoginContext instantiate a new Subject
LoginContext lc = new LoginContext("entryFoo");
t r y {
// authenticate the Subject
lc.login();
System.out.println("authentication successful");

// get the authenticated Subject

Subject subject = lc.getSubject();

. . .

// all finished - - logout

lc.logout();
} catch (LoginException le) {
System.err.println("authentication unsuccessful: " +
le.getMessage());
}

LoginModule

The L o g i n M o d u l e interface gives developers the ability to implement different kinds of authentication technologies that can
be plugged in under an application. For example, one type of L o g i n M o d u l e may perform a username/password-based
form of authentication. Other L o g i n M o d u l es may interface to hardware devices such as smart cards or biometric devices.

Note: If you are an application writer, you do not need to understand the workings of L o g i n M o d u l es. All you have to know is
how to write your application and specify configuration information (such as in a login configuration file) such that the
application will be able to utilize the LoginModule specified by the configuration to authenticate the user.

If, on the other hand, you are a programmer who wishes to write a LoginModule implementing an authentication technology,
see the JAAS L o g i n M o d u l e Developer's Guide for detailed step-by-step instructions.

CallbackHandler

In some cases a L o g i n M o d u l e must communicate with the user to obtain authentication information. L o g i n M o d u l es
use a javax.security.auth.callback.CallbackHandler for this purpose. Applications implement the C a l l b a c k H a n d l e r
interface and pass it to the L o g i n C o n t e x t, which forwards it directly to the underlying L o g i n M o d u l es. A L o g i n M o d u l e
uses the C a l l b a c k H a n d l e r both to gather input from users (such as a password or smart card pin number) or to supply
information to users (such as status information). By allowing the application to specify the C a l l b a c k H a n d l e r, underlying
L o g i n M o d u l e s can remain independent of the different ways applications interact with users. For example, the
implementation of a C a l l b a c k H a n d l e r for a GUI application might display a window to solicit input from a user. On the
other hand, the implementation of a C a l l b a c k H a n d l e r for a non-GUI tool might simply prompt the user for input directly
from the command line.

C a l l b a c k H a n d l e r is an interface with one method to implement:

Demo Version - ExpertPDF Software Components
void handle(Callback[] callbacks)
throws java.io.IOException, UnsupportedCallbackException;

The L o g i n M o d u l e passes the C a l l b a c k H a n d l e r h a n d l e method an array of appropriate C a l l b a c ks, for example a

NameCallback for the user name and a PasswordCallback for the password, and the C a l l b a c k H a n d l e r performs the
requested user interaction and sets appropriate values in the C a l l b a c ks. For example, to process a N a m e C a l l b a c k, the
C a l l b a c k H a n d l e r may prompt for a name, retrieve the value from the user, and call the N a m e C a l l b a c k's s e t N a m e
method to store the name.

The C a l l b a c k H a n d l e r documentation has a lengthy example not included in this document that readers may want to
examine.

Callback

The javax.security.auth.callback package contains the C a l l b a c k interface as well as several implementations.

L o g i n M o d u l es may pass an array of C a l l b a c ks directly to the h a n d l e method of a CallbackHandler.
Please consult the various C a l l b a c k APIs for more information on their use.

Authorization Classes

To make JAAS authorization take place, granting access control permissions based not just on what code is running but also on who is
running it, the following is required:

The user must be authenticated, as described in the LoginContext section.

The Subject that is the result of authentication must be associated with an access control context, as described in the Subject section.
Principal-based entries must be configured in the security policy, as described below.

The P o l i c y abstract class and the authorization-specific classes A u t h P e r m i s s i o n and P r i v a t e C r e d e n t i a l P e r m i s s i o n are

described below.

Policy

The j a v a . s e c u r i t y . P o l i c y class is an abstract class for representing the system-wide access control policy. The
P o l i c y API was upgraded in the J2SDK 1.4 to support P r i n c i p a l-based queries.

As a default, the J2SDK provides a file-based subclass implementation, which was upgraded to support P r i n c i p a l-based
g r a n t entries in policy files.

Policy files and the structure of entries within them are described in Default Policy Implementation and Policy File Syntax.

Sample footer: http://download.oracle.com/javase/7/docs/technotes/guides/security/jaas/JAASRefGuide.html. You can change color, font and other options Page 6 / 10
 AuthPermission

The j a v a x . s e c u r i t y . a u t h . A u t h P e r m i s s i o n class encapsulates the basic permissions required for JAAS. An

A u t h P e r m i s s i o n contains a name (also referred to as a "target name") but no actions list; you either have the named
permission or you don't.

In addition to its inherited methods (from the j a v a . s e c u r i t y . P e r m i s s i o n class), an A u t h P e r m i s s i o n has two

public constructors:

public AuthPermission(String name);

public AuthPermission(String name, String actions);

The first constructor creates a new A u t h P e r m i s s i o n with the specified name. The second constructor also creates a new
A u t h P e r m i s s i o n object with the specified name, but has an additional a c t i o n s argument which is currently unused and
should be null. This constructor exists solely for the P o l i c y object to instantiate new P e r m i s s i o n objects. For most other
code, the first constructor is appropriate.
Currently the A u t h P e r m i s s i o n object is used to guard access to the P o l i c y, S u b j e c t, L o g i n C o n t e x t, and
C o n f i g u r a t i o n objects. Please refer to the AuthPermission javadocs for the list of valid names that are supported.

PrivateCredentialPermission

The j a v a x . s e c u r i t y . a u t h . P r i v a t e C r e d e n t i a l P e r m i s s i o n class protects access to a S u b j e c t's private

credentials and provides one public constructor:

public PrivateCredentialPermission(String name, String actions);

Please refer to the PrivateCredentialPermission javadocs for more detailed information on this class.

JAAS Tutorials and Sample Programs

The JAAS Authentication and JAAS Authorization tutorials contain the following samples:

SampleAcn.java is a sample application demonstrating JAAS authentication.

SampleAzn.java is a sample application used by the authorization tutorial. It demonstrates both authentication and authorization.
sample_jaas.config is a sample login configuration file used by both tutorials.
sampleacn.policy is a sample policy file granting permissions required by the code for the authentication tutorial.
sampleazn.policy is a sample policy file granting permissions required by the code for the authorization tutorial.
SampleLoginModule.java is the class specified by the tutorials' login configuration file (s a m p l e _ j a a s . c o n f i g) as the class implementing the
desired underlying authentication. SampleLoginModule's user authentication consists of simply verifying that the name and password specified by the
user have specific values.
SamplePrincipal.java is a sample class implementing the P r i n c i p a l interface. It is used by SampleLoginModule.

Demo Version - ExpertPDF Software Components

See the tutorials for detailed information about the applications, the policy files, and the login configuration file.

Application writers do not need to understand the code for SampleLoginModule.java or SamplePrincipal.java, as explained in the tutorials. Programmers
who wish to write LoginModules can learn how to do so by reading the JAAS LoginModule Developer's Guide.

Appendix A: JAAS Settings in the java.security Security Properties File

A number of JAAS-related settings can be configured in the j a v a . s e c u r i t y master security properties file, which is located in the lib/security directory
of the Java runtime.

JAAS adds two new security properties to j a v a . s e c u r i t y:

login.configuration.provider
l o g i n . c o n f i g . u r l .n

The following pre-existing properties are also relevant for JAAS users:

policy.provider
p o l i c y . u r l .n

Login Configuration Provider

The default JAAS login configuration implementation provided by Sun Microsystems gets its configuration information from files and expects
the information to be provided in a specific format shown in the tutorials.

The default JAAS login configuration implementation can be replaced by specifying the alternative provider class implementation in the
l o g i n . c o n f i g u r a t i o n . p r o v i d e r property.

For example:

login.configuration.provider=com.foo.Config

If the Security property l o g i n . c o n f i g u r a t i o n . p r o v i d e r is not found, or is left unspecified, then it is set to the default value:

login.configuration.provider=com.sun.security.auth.login.ConfigFile

Note that there is no means to dynamically set the login configuration provider from the command line.

Login Configuration URLs

Sample footer: http://download.oracle.com/javase/7/docs/technotes/guides/security/jaas/JAASRefGuide.html. You can change color, font and other options Page 7 / 10
 If you are using a login configuration implementation that expects the configuration information to be specified in files (as does the default
implementation from Sun Microsystems), the location of the login configuration file(s) can be statically set by specifying their respective
URLs in the l o g i n . c o n f i g . u r l .n property. 'n' is a consecutively numbered integer starting with 1. If multiple configuration files are
specified (if n >= 2), they will be read and unioned into one single configuration.

For example:

login.config.url.1=file:C:/config/.java.login.config
login.config.url.2=file:C:/users/foo/.foo.login.config

If the location of the configuration files is not set in the j a v a . s e c u r i t y properties file, and also is not specified dynamically from the
command line (via the - D j a v a . s e c u r i t y . a u t h . l o g i n . c o n f i g option), JAAS attempts to load a default configuration from

f i l e : $ { u s e r . h o m e }/ . j a v a . l o g i n . c o n f i g

Policy Provider

The default policy implementation can be replaced by specifying the alternative provider class implementation in the p o l i c y . p r o v i d e r
property.

For example:

policy.provider=com.foo.Policy

If the Security property p o l i c y . p r o v i d e r is not found, or is left unspecified, then the P o l i c y is set to the default value:

policy.provider=sun.security.provider.PolicyFile

Note that there is no means to dynamically set the policy provider from the command line.

Policy File URLs

The location of the access control policy files can be statically set by specifying their respective URLs in the a u t h . p o l i c y . u r l .n
property. 'n' is a consecutively numbered integer starting with 1. If multiple policies are specified (if n >= 2), they will be read and unioned into
one single policy.

For example:

policy.url.1=file:C:/policy/.java.policy
policy.url.2=file:C:/users/foo/.foo.policy

If the location of the policy file(s) is not set in the j a v a . s e c u r i t y properties file, and is not specified dynamically from the command line
Demo Version - ExpertPDF Software Components
(via the - D j a v a . s e c u r i t y . p o l i c y option), the access control policy defaults to the same policy as that of the system policy file
installed with the J2SDK. That policy file

grants all permissions to standard extensions

allows anyone to listen on un-privileged ports
allows any code to read certain "standard" properties that are not security-sensitive, such as the "os.name" and "file.separator"
properties.

Sample Master Security Properties File

Below is a modified copy of the j a v a . s e c u r i t y file provided with the Java SE 6. Example settings for JAAS-related properties are shown
in bold. In this example, we leave the values provided in the default j a v a . s e c u r i t y file for the p o l i c y . p r o v i d e r, p o l i c y . u r l .n ,
and l o g i n . c o n f i g u r a t i o n . p r o v i d e r properties. The default j a v a . s e c u r i t y file also lists a value for the
l o g i n . c o n f i g . u r l .n property, but it is commented out. In the example below, it is not commented.

#
# This is the "master security properties file".
#
# In this file, various security properties are set for use by
# java.security classes. This is where users can statically register
# Cryptography Package Providers ("providers" for short). The term
# "provider" refers to a package or set of packages that supply a
# concrete implementation of a subset of the cryptography aspects of
# the Java Security API. A provider may, for example, implement one or
# more digital signature algorithms or message digest algorithms.
#
# Each provider must implement a subclass of the Provider class.
# To register a provider in this master security properties file,
# specify the Provider subclass name and priority in the format
#
# security.provider.<n>=<className>
#
# This declares a provider, and specifies its preference
# order <n>. The preference order is the order in which providers are
# searched for requested algorithms (when no specific provider is
# r e q u e s t e d ) . T h e o r d e r i s 1- b a s e d ; 1 i s t h e m o s t p r e f e r r e d , f o l l o w e d
# by 2, and so on.
#
# <className> must specify the subclass of the Provider class whose
# constructor sets the values of various properties that are required
# for the Java Security API to look up the algorithms or other
# facilities implemented by the provider.
#
# There must be at least one provider specification in java.security.

Sample footer: http://download.oracle.com/javase/7/docs/technotes/guides/security/jaas/JAASRefGuide.html. You can change color, font and other options Page 8 / 10
 # There is a default provider that comes standard with the JDK. It
# is called the "SUN" provider, and its Provider subclass
# named Sun appears in the sun.security.provider package. Thus, the
# "SUN" provider is registered via the following:
#
# security.provider.1=sun.security.provider.Sun
#
# (The number 1 is used for the default provider.)
#
# Note: Statically registered Provider subclasses are instantiated
# when the system is initialized. Providers can be dynamically
# registered instead by calls to either the addProvider or
# insertProviderAt method in the Security class.

#
# List of providers and their preference orders (see above):
#
security.provider.1=sun.security.provider.Sun
security.provider.2=com.sun.net.ssl.internal.ssl.Provider
security.provider.3=com.sun.rsajca.Provider
security.provider.4=com.sun.crypto.provider.SunJCE
security.provider.5=sun.security.jgss.SunProvider

#
# Select the source of seed data for SecureRandom. By default it uses
# a system/thread activity algorithm. Optionally, if the platform supports
# it an entropy gathering device can be selected.
#
#securerandom.source=file:/dev/random
#
# The entropy gathering device is described as a URL and can
# also be specified with the property "java.security.egd". For example,
# - Djava.security.egd=file:/dev/urandom
# Specifying this property will override the securerandom.source setting.

#
# Class to instantiate as the javax.security.auth.login.Configuration
# provider.
#
login.configuration.provider=com.sun.security.auth.login.ConfigFile

#
# Default login configuration file
#
login.config.url.1=file:${user.home}/.java.login.config

#
Demo Version - ExpertPDF Software Components
# Class to instantiate as the system Policy. This is the name of the class
# that will be used as the Policy object.
#
policy.provider=sun.security.provider.PolicyFile

# T h e d e f a u l t i s t o h a v e a s i n g l e s y s t e m- w i d e p o l i c y f i l e ,
# and a policy file in the user's home directory.
p olicy.url.1=file:${java.home}/lib/security/java.policy
p olicy.url.2=file:${user.home}/.java.policy

# whether or not we expand properties in the policy file

# if this is set to false, properties (${...}) will not be expanded in policy
# files.
policy.expandProperties=true

# whether or not we allow an extra policy to be passed on the command line

# w i t h - Djava.security.policy=somefile. Comment out this line to disable
# this feature.
policy.allowSystemProperty=true

# whether or not we look into the IdentityScope for trusted Identities

# when encountering a 1.1 signed JAR file. If the identity is found
# and is trusted, we grant it AllPermission.
policy.ignoreIdentityScope=false

#
# Default keystore type.
#
keystore.type=jks

#
# Class to instantiate as the system scope:
#
system.scope=sun.security.provider.IdentityDatabase

#
# L i s t o f c o m m a- s e p a r a t e d p a c k a g e s t h a t s t a r t w i t h o r e q u a l t h i s s t r i n g
# will cause a security exception to be thrown when
# passed to checkPackageAccess unless the
# corresponding RuntimePermission ("accessClassInPackage."+package) has
# been granted.
package.access=sun.

#
# L i s t o f c o m m a- s e p a r a t e d p a c k a g e s t h a t s t a r t w i t h o r e q u a l t h i s s t r i n g

Sample footer: http://download.oracle.com/javase/7/docs/technotes/guides/security/jaas/JAASRefGuide.html. You can change color, font and other options Page 9 / 10
 # will cause a security exception to be thrown when
# passed to checkPackageDefinition unless the
# corresponding RuntimePermission ("defineClassInPackage."+package) has
# been granted.
#
# by default, no packages are restricted for definition, and none of
# the class loaders supplied with the JDK call checkPackageDefinition.
#
#package.definition=

#
# Determines whether this properties file can be appended to
# or overridden on the command line via - Djava.security.properties
#
security.overridePropertiesFile=true

#
# Determines the default key and trust manager factory algorithms for
# the javax.net.ssl package.
#
ssl.KeyManagerFactory.algorithm=SunX509
ssl.TrustManagerFactory.algorithm=SunX509

#
# Determines the default SSLSocketFactory and SSLServerSocketFactory
# provider implementations for the javax.net.ssl package. If, due to
# export and/or import regulations, the providers are not allowed to be
# r e p l a c e d , c h a n g i n g t h e s e v a l u e s w i l l p r o d u c e n o n- f u n c t i o n a l
# SocketFactory or ServerSocketFactory implementations.
#
#ssl.SocketFactory.provider=
#ssl.ServerSocketFactory.provider=

Appendix B: Example Login Configurations

Login configurations are located using the l o g i n . c o n f i g . u r l . n security properties found in the j a v a . s e c u r i t y file. For more information about this property and
the location of the j a v a . s e c u r i t y file, see Appendix A.

The default Configuration implementation, C o n f i g F i l e, gets its configuration information from login configuration files. For details about the default login Configuration
implementation provided with JAAS, please consult the javadocs for the c o m . s u n . s e c u r i t y . a u t h . l o g i n . C o n f i g F i l e class.

The following is a sample login configuration file.

Login1 {
sample.SampleLoginModule required debug=true;
} ; Demo Version - ExpertPDF Software Components
Login2 {
sample.SampleLoginModule required;
com.sun.security.auth.module.NTLoginModule sufficient;
com.foo.SmartCard requisite debug=true;
com.foo.Kerberos optional debug=true;
} ;

The application Login1 only has one configured LoginModule, S a m p l e L o g i n M o d u l e. Therefore, an attempt by Login1 to authenticate a subject (user or service) will be
successful if and only if the S a m p l e L o g i n M o d u l e succeeds.

The authentication logic for the application Login2 is easier to explain with the table below. Note: the r e q u i r e d, s u f f i c i e n t, r e q u i s i t e, and o p t i o n a l flags are
described in the C o n f i g u r a t i o n javadocs.

Login2 Authentication Status

SampleLoginModule required pass pass pass pass fail fail fail fail
NTLoginModule sufficient pass fail fail fail pass fail fail fail
SmartCard requisite * pass pass fail * pass pass fail
Kerberos optional * pass fail * * pass fail *
Overall Authentication pass pass pass fail fail fail fail fail
* = trivial value due to control returning to the application because a previous requisite module failed or a previous sufficient module succeeded.

Copyright © 1993, 2010, Oracle and/or its affiliates. All rights Contact Us
reserved.
Java Technology

Scripting on this page tracks web page traffic, but does not change the content in any way.

Sample footer: http://download.oracle.com/javase/7/docs/technotes/guides/security/jaas/JAASRefGuide.html. You can change color, font and other options Page 10 / 10