This guide covers the following topics:

• 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

The Java Authentication and Authorization Service(JAAS) was introduced as an optional package (extension) to theJava 2 SDK, Standard Edition (J2SDK), v 1.3. JAASwas integrated into the J2SDK 1.4.

JAAS can be used for two purposes:

• forauthentication of users, to reliably and securelydetermine who is currently executing Java code, regardless ofwhether the code is running as an application, an applet, a bean,or a servlet; and
• forauthorization of users to ensure they have theaccess control rights (permissions) required to do the actionsperformed.

JAAS implements a Java version of the standard PluggableAuthentication Module (PAM) framework. SeeMaking LoginServices Independent from Authentication Technologies forfurther information.

Traditionally Java has provided codesource-based accesscontrols (access controls based onwhere the codeoriginated from andwho signed the code). It lacked,however, the ability to additionally enforce access controlsbased onwho runs the code. JAAS provides a framework thataugments the Java security architecture with such support.

JAAS authentication is performed in apluggablefashion. This permits applications to remain independent fromunderlying authentication technologies. New or updatedauthentication technologies can be plugged under an applicationwithout requiring modifications to the application itself.Applications enable the authentication process by instantiating aLoginContext object, which in turn references aConfiguration to determine the authenticationtechnology(ies), orLoginModule(s),to be used in performing the authentication. TypicalLoginModules may prompt for and verify a user nameand password. Others may read and verify a voice or fingerprintsample.

Once the user or service executing the code has beenauthenticated, the JAAS authorization component works inconjunction with the core Java SE access control model to protectaccess to sensitive resources. Unlike in the J2SDK 1.3 andearlier, where access control decisions are based solely on codelocation and code signers (aCodeSource),in the J2SDK 1.4 access control decisions are based both on theexecuting code'sCodeSourceand on the useror service running the code, who is represented by aSubjectobject. TheSubject is updated by aLoginModule with relevantPrincipalsand credentials if authentication succeeds.

Who Should Read This Document

This document is intended for experienced developers whorequire the ability to design applications constrained by aCodeSource-based andSubject-basedsecurity model. It is also intended to be read by LoginModuledevelopers (developers implementing an authentication technology)prior to reading theJAASLoginModule Developer's Guide.

You may wish to first read theJAAS Authentication andJAAS Authorizationtutorials to get an overview of how to use JAAS and to see samplecode in action, and then return to this document for furtherinformation.

RelatedDocumentation

This document assumes you have already read the following:

• Java SE SecurityArchitecture
• JAAS whitepaper
• JavaSE Security Tutorial

A supplement to this guide is theJAAS LoginModule Developer's Guide,intended for experienced programmers who require the ability towrite aLoginModuleimplementing an authentication technology.

If you wish to learn more about the standard PluggableAuthentication Module (PAM) framework (JAAS implements a Javaversion of PAM), seeMaking LoginServices Independent from Authentication Technologies.

The followingtutorials for JAAS authentication andauthorization can be run by everyone:

• JAAS AuthenticationTutorial
• JAAS AuthorizationTutorial

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

• JAASAuthentication
• JAASAuthorization

These two tutorials are a part of theJava GSS-API and JAAS sequence oftutorials that utilize Kerberos as the underlying technologyfor authentication and secure communication.

---

Core Classes and Interfaces

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

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

Common Classes

Common classes are those shared by both the JAAS authenticationand authorization components.

The key JAAS class isjavax.security.auth.Subject,which represents a grouping of related information for a singleentity such as a person. It encompasses the entity'sPrincipals, public credentials, and privatecredentials.

Note that thejava.security.Principal interfaceis used to represent a Principal. Also note that a credential, asdefined by JAAS, may be any Object.

Subject

To authorize access to resources, applications first need toauthenticate the source of the request. The JAAS frameworkdefines the termsubject to represent the source of arequest. A subject may be any entity, such as a person or aservice. Once the subject is authenticated, ajavax.security.auth.Subjectis populated with associated identities, orPrincipals. ASubjectmay have manyPrincipals. For example, a person mayhave a namePrincipal ("John Doe") and a SSNPrincipal ("123-45-6789"), which distinguish it fromother subjects.

ASubject may also own security-relatedattributes, which are referred to ascredentials.Sensitive credentials that require special protection, such asprivate cryptographic keys, are stored within a privatecredentialSet. Credentials intended to be shared,such as public key certificates, are stored within a publiccredentialSet. Different permissions (describedbelow) are required to access and modify the different credentialSets.

Subjects are created using these constructors:

    public Subject();    public Subject(boolean readOnly, Set principals,                   Set pubCredentials, Set privCredentials);

The first constructor creates aSubject with empty(non-null)Sets ofPrincipals andcredentials. The second constructor creates aSubject with the specifiedSets ofPrincipals and credentials. It also has a booleanargument which can be used to make theSubjectread-only. In a read-onlySubject, thePrincipal and credentialSets areimmutable.

An application writer does not have to instantiate aSubject. If the application instantiates aLoginContext and does not pass aSubject to theLoginContextconstructor, theLoginContext instantiates a newemptySubject. See theLoginContext section.

If aSubject was not instantiated to be in aread-only state, it can be set read-only by calling the followingmethod:

    public void setReadOnly();

Ajavax.security.auth.AuthPermission with target"setReadOnly" is required to invoke this method. Once in aread-only state, any attempt to add or removePrincipals or credentials will result in anIllegalStateException being thrown.

The following method may be called to test aSubject's read-only state:

    public boolean isReadOnly();

To retrieve thePrincipals associated with aSubject, two methods are available:

    public Set getPrincipals();    public Set getPrincipals(Class c);

The first method returns allPrincipals containedin theSubject, while the second method only returnsthosePrincipals that are an instance of thespecified Classc, or an instance of a subclass ofClassc. An empty set will be returned if theSubject does not have any associatedPrincipals.

To retrieve the public credentials associated with aSubject, these methods are available:

    public Set getPublicCredentials();    public Set getPublicCredentials(Class c);

The behavior of these methods is similar to that for thegetPrincipals methods, except in this case thepublic credentials are being obtained.

To access private credentials associated with aSubject, the following methods are available:

    public Set getPrivateCredentials();    public Set getPrivateCredentials(Class c);

The behavior of these methods is similar to that for thegetPrincipals andgetPublicCredentialsmethods.

To modify or operate upon aSubject'sPrincipalSet, public credentialSet, or private credentialSet, callersuse the methods defined in thejava.util.Setclass. 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: AnAuthPermission with target"modifyPrincipals", "modifyPublicCredentials", or"modifyPrivateCredentials" is required to modify the respectiveSets. Also note that only the sets returned via thegetPrincipals(),getPublicCredentials(), andgetPrivateCredentials() methods with no argumentsare backed by theSubject's respective internalsets. Therefore any modification to the returned set affects theinternal sets as well. The sets returned via thegetPrincipals(Class c),getPublicCredentials(Class c), andgetPrivateCredentials(Class c) methods are notbacked by theSubject's respective internal sets. Anew set is created and returned for each such method invocation.Modifications to these sets will not affect theSubject's internal sets.

In order to iterate through a Set of private credentials, youneed ajavax.security.auth.PrivateCredentialPermission toaccess each credential. See thePrivateCredentialPermission API documentationfor further information.

ASubject may be associated with anAccessControlContext (see thedoAs anddoAsPrivileged method descriptions below). Thefollowing method returns theSubject associated withthe specifiedAccessControlContext, ornull if noSubject is associated withthe specifiedAccessControlContext.

    public static Subject getSubject(final AccessControlContext acc);

AnAuthPermission with target "getSubject" isrequired to callSubject.getSubject.

TheSubject class also includes the followingmethods inherited fromjava.lang.Object.

    public boolean equals(Object o);    public String toString();    public int hashCode();

The doAs methods for performing an action as a particularSubject

The following static methods may be called to perform an actionas a particularSubject:

    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 specifiedsubject with the current Thread'sAccessControlContext, and then execute theaction. This achieves the effect of having theaction run as thesubject. The firstmethod can throw runtime exceptions but normal execution has itreturning an Object from therun method of itsaction argument. The second method behaves similarlyexcept that it can throw a checked exception from itsPrivilegedExceptionAction run method. AnAuthPermission with target "doAs" is required tocall thedoAs methods.

Subject.doAs Example

Here is an example utilizing the firstdoAsmethod. Assume that someone named "Bob" has been authenticated byaLoginContext (see theLoginContext section) and as a result aSubject was populated with aPrincipalof classcom.ibm.security.Principal, and thatPrincipal has the name "BOB". Also assume that aSecurityManager has been installed, and that the following existsin the access control policy (see thePolicysection 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";    };

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 section.            Subject bob;            // Set bob to the Subject created during the            // authentication process            // perform "ExampleAction" as "BOB"            Subject.doAs(bob, new ExampleAction());        }    }

During execution,ExampleAction will encounter asecurity check when it makes a call tof.exists().However, sinceExampleAction is running as "BOB",and the policy (above) grants the necessaryFilePermission to "BOB", theExampleAction will pass the security check. If thegrant statement in the policy is altered (adding anincorrectCodeBase or changing thePrincipal to "MOE", for example), then aSecurityException will be thrown.

The doAsPrivileged methods

The following methods also perform an action as a particularSubject.

    public static Object doAsPrivileged(        final Subject subject,        final java.security.PrivilegedAction action,        final java.security.AccessControlContext acc);    public static Object doAsPrivileged(        final Subject subject,        final java.security.PrivilegedExceptionAction action,        final java.security.AccessControlContext acc)        throws java.security.PrivilegedActionException;

AnAuthPermission with target "doAsPrivileged" isrequired to call thedoAsPrivileged methods.

doAs versus doAsPrivileged

ThedoAsPrivileged methods behave exactly thesame as thedoAs methods, except that instead ofassociating the providedSubject with the currentThread'sAccessControlContext, they use the providedAccessControlContext. In this way, actions can berestricted byAccessControlContexts different fromthe current one.

AnAccessControlContext contains informationabout all the code executed since theAccessControlContext was instantiated, including thecode location and the permissions the code is granted by thepolicy. In order for an access control check to succeed, thepolicy must grant each code item referenced by theAccessControlContext the required permissions.

If theAccessControlContext provided todoAsPrivileged isnull, then the actionis not restricted by a separateAccessControlContext. One example where this may beuseful is in a server environment. A server may authenticatemultiple incoming requests and perform a separatedoAs operation for each request. To start eachdoAs action "fresh," and without the restrictions ofthe current serverAccessControlContext, the servercan calldoAsPrivileged and pass in anullAccessControlContext.

Principals

As mentioned previously,Principals may beassociated with aSubject if authentication issuccessful.Principals representSubject identities, and must implement thejava.security.Principalandjava.io.Serializableinterfaces. TheSubject section describesways to update thePrincipals associated with aSubject.

Credentials

Public and private credential classes are not part of the coreJAAS class library. Any class can represent a credential.Developers, however, may elect to have their credential classesimplement two interfaces related to credentials:Refreshable andDestroyable.

Refreshable

Thejavax.security.auth.Refreshableinterface provides the capability for a credential torefresh itself. For example, a credential with a particulartime-restricted lifespan may implement this interface to allowcallers to refresh the time period for which it is valid. Theinterface has two abstract methods:

    boolean isCurrent();

This method determines whether the credential is current orvalid.

    void refresh() throws RefreshFailedException;

This method updates or extends the validity of the credential.The method implementation should perform anAuthPermission("refreshCredential") security checkto ensure the caller has permission to refresh the credential.

Destroyable

Thejavax.security.auth.Destroyableinterface provides the capability of destroying thecontents within a credential. The interface has two abstractmethods:

    boolean isDestroyed();

Determines whether the credential has been destroyed.

    void destroy() throws DestroyFailedException;

Destroys and clears the information associated with thiscredential. Subsequent calls to certain methods on thiscredential will result in anIllegalStateExceptionbeing thrown. The method implementation should perform anAuthPermission("destroyCredential") security checkto ensure the caller has permission to destroy the credential.

Authentication Classes and Interfaces

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

1. An application instantiates aLoginContext.
2. TheLoginContext consults aConfiguration to load all of theLoginModules configured for that application.
3. The application invokes theLoginContext'slogin method.
4. Thelogin method invokes all of the loadedLoginModules. EachLoginModule attemptsto authenticate the subject. Upon success,LoginModules associate relevantPrincipals and credentials with aSubject object that represents the subject beingauthenticated.
5. TheLoginContext returns the authenticationstatus to the application.
6. If authentication succeeded, the application retrieves theSubject from theLoginContext.

The authentication classes are described below.

LoginContext

Thejavax.security.auth.login.LoginContext class providesthe basic methods used to authenticate subjects, and provides away to develop an application independent of the underlyingauthentication technology. TheLoginContext consultsaConfiguration to determine the authenticationservices, orLoginModule(s),configured for a particular application. Therefore, differentLoginModules can be plugged in under an applicationwithout requiring any modifications to the applicationitself.

LoginContext offers four constructors from whichto 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 theLoginContext as an index into the loginConfiguration to determine whichLoginModules areconfigured for the application instantiating theLoginContext. Constructors that do not take aSubject as an input parameter instantiate a newSubject. Null inputs are disallowed for allconstructors. Callers require anAuthPermission withtarget "createLoginContext.<name>" to instantiate aLoginContext. Here, <name> refers to the nameof the login configuration entry that the application referencesin thename parameter for theLoginContext instantiation.

See theCallbackHandler sectionfor information on what aCallbackHandler is andwhen you may need one.

Actual authentication occurs with a call to the followingmethod:

    public void login() throws LoginException;

Whenlogin is invoked, all of the configuredLoginModules are invoked to perform theauthentication. If the authentication succeeded, theSubject (which may now holdPrincipals,public credentials, and private credentials) can be retrieved byusing the following method:

     public Subject getSubject();

To logout aSubject and remove its authenticatedPrincipals and credentials, the following method isprovided:

    public void logout() throws LoginException;

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

    // let the LoginContext instantiate a new Subject    LoginContext lc = new LoginContext("entryFoo");    try {        // 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

TheLoginModuleinterface gives developers the ability to implementdifferent kinds of authentication technologies that can beplugged in under an application. For example, one type ofLoginModule may perform a user name/password-basedform of authentication. OtherLoginModules mayinterface to hardware devices such as smart cards or biometricdevices.

Note: If you are an application writer, you do not need tounderstand the workings ofLoginModules. All youhave to know is how to write your application and specifyconfiguration information (such as in a login configuration file)such that the application will be able to utilize the LoginModulespecified by the configuration to authenticate the user.

If, on the other hand, you are a programmer who wishes towrite a LoginModule implementing an authentication technology,see theJAASLoginModule Developer's Guide for detailedstep-by-step instructions.

CallbackHandler

In some cases aLoginModule must communicate withthe user to obtain authentication information.LoginModules use ajavax.security.auth.callback.CallbackHandler for thispurpose. Applications implement theCallbackHandlerinterface and pass it to theLoginContext,which forwards it directly to the underlyingLoginModules. ALoginModule uses theCallbackHandler both to gather input from users(such as a password or smart card pin number) or to supplyinformation to users (such as status information). By allowingthe application to specify theCallbackHandler,underlyingLoginModules can remain independent ofthe different ways applications interact with users. For example,the implementation of aCallbackHandler for a GUIapplication might display a window to solicit input from a user.On the other hand, the implementation of aCallbackHandler for a non-GUI tool might simplyprompt the user for input directly from the command line.

CallbackHandler is an interface with one method toimplement:

     void handle(Callback[] callbacks)         throws java.io.IOException, UnsupportedCallbackException;

TheLoginModule passes theCallbackHandlerhandle method an array of appropriateCallbacks, for example aNameCallbackfor the user name and aPasswordCallback for the password, and theCallbackHandler performs the requested userinteraction and sets appropriate values in theCallbacks. For example, to process aNameCallback, theCallbackHandler mayprompt for a name, retrieve the value from the user, and call theNameCallback'ssetName method to storethe name.

TheCallbackHandler documentation has a lengthyexample not included in this document that readers may want toexamine.

Callback

Thejavax.security.auth.callback package contains theCallbackinterface as well as severalimplementations.LoginModules may pass an array ofCallbacks directly to thehandle methodof aCallbackHandler.

Please consult the variousCallback APIs for moreinformation on their use.

AuthorizationClasses

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

• The user must be authenticated, as described in theLoginContext section.
• The Subject that is the result of authentication must beassociated with an access control context, as described in theSubject section.
• Principal-based entries must be configured in the securitypolicy, as described below.

ThePolicy abstract class and theauthorization-specific classesAuthPermission andPrivateCredentialPermission are described below.

Policy

Thejava.security.Policyclass is anabstract class for representing thesystem-wide access control policy. ThePolicy APIwas upgraded in the J2SDK 1.4 to supportPrincipal-basedqueries.

As a default, the J2SDK provides a file-based subclassimplementation, which was upgraded to supportPrincipal-basedgrant entries in policyfiles.

Policy files and the structure of entries within them aredescribed inDefault PolicyImplementation and Policy File Syntax.

AuthPermission

Thejavax.security.auth.AuthPermissionclass encapsulates the basic permissions required for JAAS. AnAuthPermission contains a name (also referred to asa "target name") but no actions list; you either have the namedpermission or you don't.

In addition to its inherited methods (from thejava.security.Permissionclass), anAuthPermission has two publicconstructors:

    public AuthPermission(String name);    public AuthPermission(String name, String actions);

The first constructor creates a newAuthPermissionwith the specified name. The second constructor also creates anewAuthPermission object with the specified name,but has an additionalactions argument which iscurrently unused and should be null. This constructor existssolely for thePolicy object to instantiate newPermission objects. For most other code, the firstconstructor is appropriate.

Currently theAuthPermission object is used toguard access to thePolicy,Subject,LoginContext, andConfigurationobjects. Please refer to theAuthPermissionjavadocs for the list of valid names that are supported.

PrivateCredentialPermission

Thejavax.security.auth.PrivateCredentialPermissionclass protects access to aSubject's privatecredentials and provides one public constructor:

     public PrivateCredentialPermission(String name, String actions);

Please refer to thePrivateCredentialPermission javadocs for more detailedinformation on this class.

---

JAAS Tutorials and SamplePrograms

TheJAASAuthentication andJAAS Authorizationtutorials contain the following samples:

• SampleAcn.java is asample application demonstrating JAAS authentication.
• SampleAzn.java is asample application used by the authorization tutorial. Itdemonstrates both authentication and authorization.
• sample_jaas.configis a sample login configuration file used by both tutorials.
• sampleacn.policy isa sample policy file granting permissions required by the codefor the authentication tutorial.
• sampleazn.policy isa sample policy file granting permissions required by the codefor the authorization tutorial.
• SampleLoginModule.java isthe class specified by the tutorials' login configuration file(sample_jaas.config) as the class implementing thedesired underlying authentication. SampleLoginModule's userauthentication consists of simply verifying that the name andpassword specified by the user have specific values.
• SamplePrincipal.java is asample class implementing thePrincipalinterface. It is used by SampleLoginModule.

See the tutorials for detailed information about theapplications, the policy files, and the login configurationfile.

Application writers do not need to understand the code forSampleLoginModule.java or SamplePrincipal.java, as explained inthe tutorials. Programmers who wish to write LoginModules canlearn how to do so by reading theJAAS LoginModule Developer's Guide.

---

Appendix A: JAAS Settingsin the java.security Security Properties File

A number of JAAS-related settings can be configured in thejava.security master security properties file, whichis located in thelib/security directory of the Javaruntime.

JAAS adds two new security properties tojava.security:

• login.configuration.provider
• login.config.url.n

The following pre-existing properties are also relevant forJAAS users:

• policy.provider
• policy.url.n

The following example demonstrates how to configure these properties.In this example, we leave the values provided in the defaultjava.security file for thepolicy.provider,policy.url.n, andlogin.configuration.provider properties. The defaultjava.security file also lists a value for thelogin.config.url.n property, but it is commented out. In the example below, it is not commented.

...## 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## 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# The default is to have a single system-wide policy file,# and a policy file in the user's home directory.policy.url.1=file:${java.home}/lib/security/java.policypolicy.url.2=file:${user.home}/.java.policy...

Note: Modifications made to this file may be overwritten by subsequent JRE updates. However, an alternatejava.security properties file may be specified from the command line via the system propertyjava.security.properties=<URL>.This properties file appends to the system properties file. If both properties files specify values for the same key, the value from command-line properties file is selected, as it is the last one loaded.

Also, specifyingjava.security.properties==<URL> (using two equals signs), then that properties file will completely override the system properties file.

To disable the ability to specify an additional properties file from the command line, set the keysecurity.overridePropertiesFiletofalse in the system properties file. It is set totrue by default.

Login Configuration Provider

The default JAAS login configuration implementation providedby Oracle gets its configuration information from filesand expects the information to be provided in a specific formatshown in the tutorials.

The default JAAS login configuration implementation can bereplaced by specifying the alternative provider classimplementation in thelogin.configuration.providerproperty.

For example:

  login.configuration.provider=com.foo.Config

If the Security propertylogin.configuration.provider is not found, or isleft 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 loginconfiguration provider from the command line.

Login Configuration URLs

If you are using a login configuration implementation thatexpects the configuration information to be specified in files(as does the default implementation from Oracle), thelocation of the login configuration file(s) can be statically setby specifying their respective URLs in thelogin.config.url.n property. 'n' is aconsecutively numbered integer starting with 1. If multipleconfiguration files are specified (ifn >= 2), theywill 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 thejava.security properties file, and also is notspecified dynamically from the command line (via the-Djava.security.auth.login.config option), JAASattempts to load a default configuration from

file:${user.home}/.java.login.config

Policy Provider

The default policy implementation can be replaced byspecifying the alternative provider class implementation in thepolicy.provider property.

For example:

  policy.provider=com.foo.Policy

If the Security propertypolicy.provider is notfound, or is left unspecified, then thePolicy isset to the default value:

  policy.provider=sun.security.provider.PolicyFile

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

Policy File URLs

The location of the access control policy files can bestatically set by specifying their respective URLs in theauth.policy.url.n property. 'n' is aconsecutively numbered integer starting with 1. If multiplepolicies are specified (ifn >= 2), they will be readand 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 thejava.security properties file, and is not specifieddynamically from the command line (via the-Djava.security.policy option), the access controlpolicy defaults to the same policy as that of the system policyfile 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 thatare not security-sensitive, such as the "os.name" and"file.separator" properties.

---

Appendix B: Example LoginConfigurations

Login configurations are located using thelogin.config.url.n security properties found in thejava.security file. For more information about thisproperty and the location of thejava.security file,seeAppendix A.

The default Configuration implementation,ConfigFile, gets its configuration information fromlogin configuration files. For details about the default loginConfiguration implementation provided with JAAS, please consultthe javadocs for thecom.sun.security.auth.login.ConfigFileclass.

The following is a sample login configuration file.

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

The applicationLogin1 only has one configuredLoginModule,SampleLoginModule. Therefore, anattempt byLogin1 to authenticate a subject (user orservice) will be successful if and only if theSampleLoginModule succeeds.

The authentication logic for the applicationLogin2 iseasier to explain with the table below. Note: therequired,sufficient,requisite, andoptional flags aredescribed in theConfiguration javadocs.

Login2 Authentication Status

Module Class	Flag	Authentication Attempt 1	Authentication Attempt 2	Authentication Attempt 3	Authentication Attempt 4	Authentication Attempt 5	Authentication Attempt 6	Authentication Attempt 7	Authentication Attempt 8
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	not applicable	pass	pass	pass	fail	fail	fail	fail	fail

* = trivial value due to control returning to the applicationbecause a previousrequisite module failed or a previoussufficient module succeeded.

©2009-2025 Movatter.jp