JavaTM Authentication and Authorization Service

8/7/2019 JavaTM Authentication and Authorization Service

1/22

Java TM Authentication and Authorization Service (JAAS)

Reference Guide

for the Java TM 2 SDK, Standard Edition, v 1.4

Introduction Who Should Read This Document

Related Documentation

What's New in JAAS in the J2SDK, v 1.4Core 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 ProgramsAppendix A: JAAS Settings in the java.security Security Properties FileAppendix B: Example Login Configurations
http://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/JAASRefGuide.html#Who%23Whohttp://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/JAASRefGuide.html#RelatedDocs%23RelatedDocshttp://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/JAASRefGuide.html#WhatsNew%23WhatsNewhttp://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/JAASRefGuide.html#Core%23Corehttp://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/JAASRefGuide.html#Core%23Corehttp://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/JAASRefGuide.html#Common%23Commonhttp://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/JAASRefGuide.html#Subject%23Subjecthttp://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/JAASRefGuide.html#Principals%23Principalshttp://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/JAASRefGuide.html#Credentials%23Credentialshttp://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/JAASRefGuide.html#Authentication%23Authenticationhttp://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/JAASRefGuide.html#LoginContext%23LoginContexthttp://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/JAASRefGuide.html#LoginModule%23LoginModulehttp://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/JAASRefGuide.html#CallbackHandler%23CallbackHandlerhttp://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/JAASRefGuide.html#Callback%23Callbackhttp://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/JAASRefGuide.html#Authorization%23Authorizationhttp://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/JAASRefGuide.html#Policy%23Policyhttp://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/JAASRefGuide.html#AuthPermission%23AuthPermissionhttp://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/JAASRefGuide.html#PrivateCredentialPermission%23PrivateCredentialPermissionhttp://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/JAASRefGuide.html#Sample%23Samplehttp://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/JAASRefGuide.html#AppendixA%23AppendixAhttp://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/JAASRefGuide.html#AppendixB%23AppendixBhttp://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/JAASRefGuide.html#RelatedDocs%23RelatedDocshttp://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/JAASRefGuide.html#WhatsNew%23WhatsNewhttp://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/JAASRefGuide.html#Core%23Corehttp://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/JAASRefGuide.html#Common%23Commonhttp://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/JAASRefGuide.html#Subject%23Subjecthttp://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/JAASRefGuide.html#Principals%23Principalshttp://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/JAASRefGuide.html#Credentials%23Credentialshttp://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/JAASRefGuide.html#Authentication%23Authenticationhttp://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/JAASRefGuide.html#LoginContext%23LoginContexthttp://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/JAASRefGuide.html#LoginModule%23LoginModulehttp://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/JAASRefGuide.html#CallbackHandler%23CallbackHandlerhttp://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/JAASRefGuide.html#Callback%23Callbackhttp://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/JAASRefGuide.html#Authorization%23Authorizationhttp://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/JAASRefGuide.html#Policy%23Policyhttp://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/JAASRefGuide.html#AuthPermission%23AuthPermissionhttp://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/JAASRefGuide.html#PrivateCredentialPermission%23PrivateCredentialPermissionhttp://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/JAASRefGuide.html#Sample%23Samplehttp://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/JAASRefGuide.html#AppendixA%23AppendixAhttp://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/JAASRefGuide.html#AppendixB%23AppendixBhttp://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/JAASRefGuide.html#Who%23Who


2/22

IntroductionThe Java TM Authentication and Authorization Service (JAAS) was introduced as an optional package(extension) to the Java TM 2 SDK, Standard Edition (J2SDK), v 1.3. JAAS has now been integrated into theJ2SDK, v 1.4.

JAAS can be used for two purposes:

for authentication of users, to reliably and securely determine who is currently executing Javacode, 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 todo the actions performed.

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

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

JAAS authentication is performed in a pluggable fashion. This permits applications to remain independentfrom underlying authentication technologies. New or updated authentication technologies can be pluggedunder an application without requiring modifications to the application itself. Applications enable theauthentication process by instantiating a LoginContext object, which in turn references aConfiguration to determine the authentication technology(ies), or LoginModule (s), to be used in

performing the authentication. Typical LoginModule s 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 componentworks in conjunction with the core Java 2 access control model to protect access to sensitive resources.Unlike in the J2SDK, v 1.3 and earlier, where access control decisions are based solely on code locationand code signers (a CodeSource ), in the J2SDK, v 1.4 access control decisions are based both on theexecuting code's CodeSource and on the user or service running the code, who is represented by aSubject object. The Subject is updated by a LoginModule with relevant Principal s andcredentials if authentication succeeds.

Who Should Read This Document

This document is intended for experienced developers who require the ability to design applicationsconstrained by a CodeSource -based and Subject -based security model. It is also intended to be read by LoginModule developers (developers implementing an authentication technology) prior to reading theJAAS LoginModule Developer's Guide .

You may wish to first read the JAAS Authentication and JAAS Authorization tutorials to get an overviewof how to use JAAS and to see sample code in action, and then return to this document for further information.
http://java.sun.com/security/jaas/doc/pam.htmlhttp://download.oracle.com/javase/1.4.2/docs/api/javax/security/auth/login/LoginContext.htmlhttp://download.oracle.com/javase/1.4.2/docs/api/javax/security/auth/login/Configuration.htmlhttp://download.oracle.com/javase/1.4.2/docs/api/javax/security/auth/spi/LoginModule.htmlhttp://download.oracle.com/javase/1.4.2/docs/api/javax/security/auth/spi/LoginModule.htmlhttp://download.oracle.com/javase/1.4.2/docs/api/javax/security/auth/spi/LoginModule.htmlhttp://download.oracle.com/javase/1.4.2/docs/api/java/security/CodeSource.htmlhttp://download.oracle.com/javase/1.4.2/docs/api/java/security/CodeSource.htmlhttp://download.oracle.com/javase/1.4.2/docs/api/javax/security/auth/Subject.htmlhttp://download.oracle.com/javase/1.4.2/docs/api/java/security/Principal.htmlhttp://download.oracle.com/javase/1.4.2/docs/api/java/security/Principal.htmlhttp://download.oracle.com/javase/1.4.2/docs/api/java/security/Principal.htmlhttp://download.oracle.com/javase/1.4.2/docs/api/java/security/Principal.htmlhttp://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/JAASLMDevGuide.htmlhttp://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/JAASLMDevGuide.htmlhttp://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/tutorials/GeneralAcnOnly.htmlhttp://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/tutorials/GeneralAcnOnly.htmlhttp://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/tutorials/GeneralAcnAndAzn.htmlhttp://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/tutorials/GeneralAcnAndAzn.htmlhttp://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/tutorials/GeneralAcnAndAzn.htmlhttp://java.sun.com/security/jaas/doc/pam.htmlhttp://download.oracle.com/javase/1.4.2/docs/api/javax/security/auth/login/LoginContext.htmlhttp://download.oracle.com/javase/1.4.2/docs/api/javax/security/auth/login/Configuration.htmlhttp://download.oracle.com/javase/1.4.2/docs/api/javax/security/auth/spi/LoginModule.htmlhttp://download.oracle.com/javase/1.4.2/docs/api/java/security/CodeSource.htmlhttp://download.oracle.com/javase/1.4.2/docs/api/javax/security/auth/Subject.htmlhttp://download.oracle.com/javase/1.4.2/docs/api/java/security/Principal.htmlhttp://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/JAASLMDevGuide.htmlhttp://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/tutorials/GeneralAcnOnly.htmlhttp://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/tutorials/GeneralAcnAndAzn.html


3/22

Related Documentation

This document assumes you have already read the following:

Java 2 Security Architecture Java 2 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 LoginModule implementing an authenticationtechnology.

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

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 KerberosLoginModule 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 asthe underlying technology for authentication and secure communication.

What's New in JAAS in the J2SDK, v 1.4Below are listed the differences between the previous version of JAAS (JAAS 1.0) and the JAAS withinthe J2SDK, v 1.4.

JAAS Is Now in J2SDK New Classes/Interfaces Deprecated Items

JAAS Is Now in J2SDK

JAAS was previously an optional package (extension) to the Java TM 2 SDK, Standard Edition (J2SDK),versions 1.3.x. JAAS has now been integrated into the J2SDK, v 1.4. JAAS augments the core Java 2

platform with the means to authenticate and enforce access controls upon users.

The major ramification of this integration stems around the system security policy. The J2SDK, versions1.3 and earlier, has its own security policy class ( java.security.Policy ). JAAS 1.0, as an optional

package, provided an additional Principal -based security policy(javax.security.auth.Policy ). Upon integration into the core SDK, the JAAS policy has beendeprecated in favor of the SDK policy.
http://download.oracle.com/javase/1.4.2/docs/guide/security/spec/security-spec.doc.htmlhttp://java.sun.com/docs/books/tutorial/security1.2/index.htmlhttp://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/JAASLMDevGuide.htmlhttp://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/JAASLMDevGuide.htmlhttp://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/JAASLMDevGuide.htmlhttp://download.oracle.com/javase/1.4.2/docs/api/javax/security/auth/spi/LoginModule.htmlhttp://download.oracle.com/javase/1.4.2/docs/api/javax/security/auth/spi/LoginModule.htmlhttp://download.oracle.com/javase/1.4.2/docs/api/javax/security/auth/spi/LoginModule.htmlhttp://java.sun.com/security/jaas/doc/pam.htmlhttp://java.sun.com/security/jaas/doc/pam.htmlhttp://java.sun.com/security/jaas/doc/pam.htmlhttp://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/tutorials/GeneralAcnOnly.htmlhttp://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/tutorials/GeneralAcnAndAzn.htmlhttp://download.oracle.com/javase/1.4.2/docs/guide/security/jgss/tutorials/AcnOnly.htmlhttp://download.oracle.com/javase/1.4.2/docs/guide/security/jgss/tutorials/AcnAndAzn.htmlhttp://download.oracle.com/javase/1.4.2/docs/guide/security/jgss/tutorials/index.htmlhttp://download.oracle.com/javase/1.4.2/docs/guide/security/jgss/tutorials/index.htmlhttp://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/JAASRefGuide.html#InJ2%23InJ2http://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/JAASRefGuide.html#NewMethods%23NewMethodshttp://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/JAASRefGuide.html#Deprecated%23Deprecatedhttp://download.oracle.com/javase/1.4.2/docs/api/java/security/Policy.htmlhttp://download.oracle.com/javase/1.4.2/docs/api/java/security/Policy.htmlhttp://download.oracle.com/javase/1.4.2/docs/guide/security/spec/security-spec.doc.htmlhttp://java.sun.com/docs/books/tutorial/security1.2/index.htmlhttp://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/JAASLMDevGuide.htmlhttp://download.oracle.com/javase/1.4.2/docs/api/javax/security/auth/spi/LoginModule.htmlhttp://java.sun.com/security/jaas/doc/pam.htmlhttp://java.sun.com/security/jaas/doc/pam.htmlhttp://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/tutorials/GeneralAcnOnly.htmlhttp://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/tutorials/GeneralAcnAndAzn.htmlhttp://download.oracle.com/javase/1.4.2/docs/guide/security/jgss/tutorials/AcnOnly.htmlhttp://download.oracle.com/javase/1.4.2/docs/guide/security/jgss/tutorials/AcnAndAzn.htmlhttp://download.oracle.com/javase/1.4.2/docs/guide/security/jgss/tutorials/index.htmlhttp://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/JAASRefGuide.html#InJ2%23InJ2http://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/JAASRefGuide.html#NewMethods%23NewMethodshttp://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/JAASRefGuide.html#Deprecated%23Deprecatedhttp://download.oracle.com/javase/1.4.2/docs/api/java/security/Policy.html


4/22

The SDK Policy API was upgraded to support Principal - based queries, and the Policy referenceimplementation was upgraded to support Principal -based grant entries in policy files, where such anentry may include a Principal field indicating that the user or other entity represented by the specifiedPrincipal , executing the specified code, has the designated permissions. In addition, the graphicalPolicy Tool utility used to create policy files was enhanced to support inclusion of Principal fields.Appropriately, the JAAS 1.0 Policy reference implementation and its supporting classes in the

com.sun.security.auth package have been deprecated.

Please reference the Policy Document for more information on the Policy reference implementation anda list of the relevant API changes.

New Classes/Interfaces

Additions include

Two default CallbackHandler implementations:o com.sun.security.auth.callback.DialogCallbackHandler o com.sun.security.auth.callback.TextCallbackHandler

New com.sun.security.auth.module.Krb5LoginModule New com.sun.security.auth.module.KeyStoreLoginModule

Deprecated Items

Deprecated items include:

Deprecation of o com.sun.security.auth.module.SolarisLoginModule

in favor of

o com.sun.security.auth.module.UnixLoginModule

The new UnixLoginModule can be used on both Solaris and Linux.

Deprecation of o com.sun.security.auth.SolarisPrincipal

in favor of

o com.sun.security.auth.UnixPrincipal Deprecation of

o com.sun.security.auth.SolarisNumericUserPrincipal

in favor of

o com.sun.security.auth.UnixNumericUserPrincipal Deprecation of

o com.sun.security.auth.SolarisNumericGroupPrincipal

in favor of
http://download.oracle.com/javase/1.4.2/docs/api/java/security/Principal.htmlhttp://download.oracle.com/javase/1.4.2/docs/api/java/security/Principal.htmlhttp://download.oracle.com/javase/1.4.2/docs/api/java/security/Principal.htmlhttp://download.oracle.com/javase/1.4.2/docs/guide/security/SecurityToolsSummary.htmlhttp://download.oracle.com/javase/1.4.2/docs/guide/security/PolicyFiles.htmlhttp://download.oracle.com/javase/1.4.2/docs/guide/security/PolicyFiles.htmlhttp://download.oracle.com/javase/1.4.2/docs/guide/security/PolicyFiles.htmlhttp://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/spec/com/sun/security/auth/callback/DialogCallbackHandler.htmlhttp://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/spec/com/sun/security/auth/callback/DialogCallbackHandler.htmlhttp://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/spec/com/sun/security/auth/callback/TextCallbackHandler.htmlhttp://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/spec/com/sun/security/auth/callback/TextCallbackHandler.htmlhttp://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/spec/com/sun/security/auth/module/Krb5LoginModule.htmlhttp://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/spec/com/sun/security/auth/module/Krb5LoginModule.htmlhttp://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/spec/com/sun/security/auth/module/Krb5LoginModule.htmlhttp://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/spec/com/sun/security/auth/module/KeyStoreLoginModule.htmlhttp://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/spec/com/sun/security/auth/module/KeyStoreLoginModule.htmlhttp://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/spec/com/sun/security/auth/module/KeyStoreLoginModule.htmlhttp://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/spec/com/sun/security/auth/module/SolarisLoginModule.htmlhttp://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/spec/com/sun/security/auth/module/SolarisLoginModule.htmlhttp://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/spec/com/sun/security/auth/module/UnixLoginModule.htmlhttp://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/spec/com/sun/security/auth/module/UnixLoginModule.htmlhttp://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/spec/com/sun/security/auth/SolarisPrincipal.htmlhttp://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/spec/com/sun/security/auth/SolarisPrincipal.htmlhttp://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/spec/com/sun/security/auth/UnixPrincipal.htmlhttp://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/spec/com/sun/security/auth/UnixPrincipal.htmlhttp://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/spec/com/sun/security/auth/SolarisNumericUserPrincipal.htmlhttp://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/spec/com/sun/security/auth/SolarisNumericUserPrincipal.htmlhttp://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/spec/com/sun/security/auth/UnixNumericUserPrincipal.htmlhttp://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/spec/com/sun/security/auth/UnixNumericUserPrincipal.htmlhttp://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/spec/com/sun/security/auth/SolarisNumericGroupPrincipal.htmlhttp://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/spec/com/sun/security/auth/SolarisNumericGroupPrincipal.htmlhttp://download.oracle.com/javase/1.4.2/docs/api/java/security/Principal.htmlhttp://download.oracle.com/javase/1.4.2/docs/guide/security/SecurityToolsSummary.htmlhttp://download.oracle.com/javase/1.4.2/docs/guide/security/PolicyFiles.htmlhttp://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/spec/com/sun/security/auth/callback/DialogCallbackHandler.htmlhttp://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/spec/com/sun/security/auth/callback/TextCallbackHandler.htmlhttp://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/spec/com/sun/security/auth/module/Krb5LoginModule.htmlhttp://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/spec/com/sun/security/auth/module/KeyStoreLoginModule.htmlhttp://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/spec/com/sun/security/auth/module/SolarisLoginModule.htmlhttp://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/spec/com/sun/security/auth/module/UnixLoginModule.htmlhttp://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/spec/com/sun/security/auth/SolarisPrincipal.htmlhttp://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/spec/com/sun/security/auth/UnixPrincipal.htmlhttp://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/spec/com/sun/security/auth/SolarisNumericUserPrincipal.htmlhttp://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/spec/com/sun/security/auth/UnixNumericUserPrincipal.htmlhttp://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/spec/com/sun/security/auth/SolarisNumericGroupPrincipal.html


5/22

o com.sun.security.auth.UnixNumericGroupPrincipal Deprecation of

o com.sun.security.auth.X500Principal

in favor of

o javax.security.auth.x500.X500Principal Deprecation of the javax.security.auth.AuthPermission target name

o "createLoginContext"

in favor of

o "createLoginContext.{configuration entry name}"
http://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/spec/com/sun/security/auth/UnixNumericGroupPrincipal.htmlhttp://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/spec/com/sun/security/auth/UnixNumericGroupPrincipal.htmlhttp://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/spec/com/sun/security/auth/X500Principal.htmlhttp://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/spec/com/sun/security/auth/X500Principal.htmlhttp://download.oracle.com/javase/1.4.2/docs/api/javax/security/auth/x500/X500Principal.htmlhttp://download.oracle.com/javase/1.4.2/docs/api/javax/security/auth/x500/X500Principal.htmlhttp://download.oracle.com/javase/1.4.2/docs/api/javax/security/auth/AuthPermission.htmlhttp://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/spec/com/sun/security/auth/UnixNumericGroupPrincipal.htmlhttp://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/spec/com/sun/security/auth/X500Principal.htmlhttp://download.oracle.com/javase/1.4.2/docs/api/javax/security/auth/x500/X500Principal.htmlhttp://download.oracle.com/javase/1.4.2/docs/api/javax/security/auth/AuthPermission.html


6/22

Core Classes and InterfacesThe JAAS-related core classes and interfaces can be broken into 3 categories: Common, Authentication,and Authorization.

Common Classeso Subject , Principal , Credential (actually, any Object)

Authentication Classes and Interfaceso LoginContext , LoginModule , CallbackHandler , Callback

Authorization Classeso Policy , AuthPermission , PrivateCredentialPermission

Common Classes

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

The key JAAS class is javax.security.auth.Subject , which represents a grouping of relatedinformation for a single entity such as a person. It encompasses the entity's Principals , public credentials,and private credentials.

Note that the java.security.Principal interface is used to represent a Principal. Also note that acredential, as defined by JAAS, may be any Object.

Subject

To authorize access to resources, applications first need to authenticate the source of the request. The JAASframework defines the term subject to represent the source of a request. A subject may be any entity, suchas a person or a service. Once the subject is authenticated, a javax.security.auth.Subject is

populated with associated identities, or Principal s . A Subject may have many Principal s. For example, a person may have a name Principal ("John Doe") and a SSN Principal ("123-45-6789"),which distinguish it from other subjects.

A Subject may also own security-related attributes, which are referred to as credentials . Sensitivecredentials that require special protection, such as private cryptographic keys, are stored within a privatecredential Set . Credentials intended to be shared, such as public key certificates, are stored within a publiccredential Set . Different permissions (described below) are required to access and modify the differentcredential Set s.

Subjects are created using these constructors:

public Subject();

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

The first constructor creates a Subject with empty (non-null) Set s of Principal s and credentials.The second constructor creates a Subject with the specified Set s of Principal s and credentials. Italso has a boolean argument which can be used to make the Subject read-only. In a read-onlySubject , the Principal and credential Set s are immutable.
http://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/JAASRefGuide.html#Common%23Commonhttp://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/JAASRefGuide.html#Subject%23Subjecthttp://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/JAASRefGuide.html#Principals%23Principalshttp://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/JAASRefGuide.html#Credentials%23Credentialshttp://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/JAASRefGuide.html#Authentication%23Authenticationhttp://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/JAASRefGuide.html#LoginContext%23LoginContexthttp://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/JAASRefGuide.html#LoginContext%23LoginContexthttp://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/JAASRefGuide.html#LoginModule%23LoginModulehttp://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/JAASRefGuide.html#LoginModule%23LoginModulehttp://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/JAASRefGuide.html#LoginModule%23LoginModulehttp://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/JAASRefGuide.html#CallbackHandler%23CallbackHandlerhttp://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/JAASRefGuide.html#CallbackHandler%23CallbackHandlerhttp://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/JAASRefGuide.html#CallbackHandler%23CallbackHandlerhttp://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/JAASRefGuide.html#Callback%23Callbackhttp://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/JAASRefGuide.html#Callback%23Callbackhttp://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/JAASRefGuide.html#Authorization%23Authorizationhttp://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/JAASRefGuide.html#Policy%23Policyhttp://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/JAASRefGuide.html#Policy%23Policyhttp://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/JAASRefGuide.html#AuthPermission%23AuthPermissionhttp://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/JAASRefGuide.html#AuthPermission%23AuthPermissionhttp://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/JAASRefGuide.html#PrivateCredentialPermission%23PrivateCredentialPermissionhttp://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/JAASRefGuide.html#PrivateCredentialPermission%23PrivateCredentialPermissionhttp://download.oracle.com/javase/1.4.2/docs/api/javax/security/auth/Subject.htmlhttp://download.oracle.com/javase/1.4.2/docs/api/javax/security/auth/Subject.htmlhttp://download.oracle.com/javase/1.4.2/docs/api/javax/security/auth/Subject.htmlhttp://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/JAASRefGuide.html#Principals%23Principalshttp://download.oracle.com/javase/1.4.2/docs/api/javax/security/auth/Subject.htmlhttp://download.oracle.com/javase/1.4.2/docs/api/javax/security/auth/Subject.htmlhttp://download.oracle.com/javase/1.4.2/docs/api/javax/security/auth/Subject.htmlhttp://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/JAASRefGuide.html#Principals%23Principalshttp://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/JAASRefGuide.html#Principals%23Principalshttp://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/JAASRefGuide.html#Principals%23Principalshttp://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/JAASRefGuide.html#Principals%23Principalshttp://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/JAASRefGuide.html#Principals%23Principalshttp://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/JAASRefGuide.html#Principals%23Principalshttp://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/JAASRefGuide.html#Common%23Commonhttp://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/JAASRefGuide.html#Subject%23Subjecthttp://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/JAASRefGuide.html#Principals%23Principalshttp://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/JAASRefGuide.html#Credentials%23Credentialshttp://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/JAASRefGuide.html#Authentication%23Authenticationhttp://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/JAASRefGuide.html#LoginContext%23LoginContexthttp://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/JAASRefGuide.html#LoginModule%23LoginModulehttp://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/JAASRefGuide.html#CallbackHandler%23CallbackHandlerhttp://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/JAASRefGuide.html#Callback%23Callbackhttp://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/JAASRefGuide.html#Authorization%23Authorizationhttp://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/JAASRefGuide.html#Policy%23Policyhttp://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/JAASRefGuide.html#AuthPermission%23AuthPermissionhttp://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/JAASRefGuide.html#PrivateCredentialPermission%23PrivateCredentialPermissionhttp://download.oracle.com/javase/1.4.2/docs/api/javax/security/auth/Subject.htmlhttp://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/JAASRefGuide.html#Principals%23Principalshttp://download.oracle.com/javase/1.4.2/docs/api/javax/security/auth/Subject.htmlhttp://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/JAASRefGuide.html#Principals%23Principals


7/22

An application writer does not have to instantiate a Subject . If the application instantiates aLoginContext and does not pass a Subject to the LoginContext constructor, theLoginContext instantiates a new empty Subject . See the LoginContext section .

If a Subject was not instantiated to be in a read-only state, it can be set read-only by calling thefollowing method:

public void setReadOnly();A javax.security.auth.AuthPermission with target "setReadOnly" is required to invoke thismethod. Once in a read-only state, any attempt to add or remove Principal s or credentials will result inan IllegalStateException being thrown.

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

public boolean isReadOnly();

To retrieve the Principal s associated with a Subject, two methods are available:

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

The first method returns all Principal s contained in the Subject , while the second method onlyreturns those Principal s 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 Subject does not have any associated Principal s.

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

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

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

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

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

The behavior of these methods is similar to that for the getPrincipals andgetPublicCredentials methods.

To modify or operate upon a Subject 's Principal Set , public credential Set , or private credential

Set , callers use the methods defined in the java.util.Set class. The following example demonstratesthis:

Subject subject;Principal principal;Object credential;

. . .
http://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/JAASRefGuide.html#LoginContext%23LoginContexthttp://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/JAASRefGuide.html#LoginContext%23LoginContexthttp://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/JAASRefGuide.html#LoginContext%23LoginContexthttp://download.oracle.com/javase/1.4.2/docs/api/java/util/Set.htmlhttp://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/JAASRefGuide.html#LoginContext%23LoginContexthttp://download.oracle.com/javase/1.4.2/docs/api/java/util/Set.html


8/22

// add a Principal and credential to the Subjectsubject.getPrincipals().add(principal);subject.getPublicCredentials().add(credential);

Note: An AuthPermission with target "modifyPrincipals", "modifyPublicCredentials", or "modifyPrivateCredentials" is required to modify the respective Set s. Also note that only the sets returned

via the getPrincipals() , getPublicCredentials() , and getPrivateCredentials()methods with no arguments are backed by the Subject 's respective internal sets. Therefore anymodification to the returned set affects the internal sets as well. The sets returned via thegetPrincipals(Class c) , getPublicCredentials(Class c) , andgetPrivateCredentials(Class c) methods are not backed by the Subject 's respective internalsets. A new set is created and returned for each such method invocation. Modifications to these sets will notaffect the Subject 's internal sets.

In order to iterate through a Set of private credentials, you need ajavax.security.auth.PrivateCredentialPermission to access each credential. See thePrivateCredentialPermission API documentation for further information.

ASubject

may be associated with anAccessControlContext

(see thedoAs

anddoAsPrivileged method descriptions below). The following method returns the Subject associatedwith the specified AccessControlContext , or null if no Subject is associated with the specifiedAccessControlContext .

public static Subject getSubject(final AccessControlContext acc);

An AuthPermission with target "getSubject" is required to call Subject.getSubject .

The Subject class also includes the following methods inherited from java.lang.Object .

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 Subject :public static Object

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

public static ObjectdoAs(final Subject subject,

final java.security.PrivilegedExceptionAction action)

throws java.security.PrivilegedActionException;

Both methods first associate the specified subject with the current Thread'sAccessControlContext , and then execute the action . This achieves the effect of having theaction run as the subject . The first method can throw runtime exceptions but normal execution has itreturning an Object from the run method of its action argument. The second method behaves similarlyexcept that it can throw a checked exception from its PrivilegedExceptionAction run method.An AuthPermission with target "doAs" is required to call the doAs methods.
http://download.oracle.com/javase/1.4.2/docs/api/javax/security/auth/PrivateCredentialPermission.htmlhttp://download.oracle.com/javase/1.4.2/docs/api/javax/security/auth/PrivateCredentialPermission.html


9/22

Subject.doAs Example

Here is an example utilizing the first doAs method. Assume that someone named "Bob" has beenauthenticated by a LoginContext (see the LoginContext section) and as a result a Subject was

populated with a Principal of class com.ibm.security.Principal , and that Principal hasthe name "BOB". Also assume that a SecurityManager has been installed, and that the following exists inthe 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";};

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 checkif (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 a security check when it makes a call tof.exists() . However, since ExampleAction is running as "BOB", and the policy (above) grants the

necessary FilePermission to "BOB", the ExampleAction will pass the security check. If thegrant statement in the policy is altered (adding an incorrect CodeBase or changing the Principal to"MOE", for example), then a SecurityException will be thrown.

The doAsPrivileged methods

The following methods also perform an action as a particular Subject .
http://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/JAASRefGuide.html#LoginContext%23LoginContexthttp://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/JAASRefGuide.html#Policy%23Policyhttp://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/JAASRefGuide.html#Policy%23Policyhttp://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/JAASRefGuide.html#LoginContext%23LoginContexthttp://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/JAASRefGuide.html#LoginContext%23LoginContexthttp://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/JAASRefGuide.html#Policy%23Policyhttp://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/JAASRefGuide.html#LoginContext%23LoginContext


10/22

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;

An AuthPermission with target "doAsPrivileged" is required to call the doAsPrivileged methods.

doAs vs. doAsPrivileged

The doAsPrivileged methods behave exactly the same as the doAs methods, except that instead of associating the provided Subject with the current Thread's AccessControlContext , they use the

provided AccessControlContext . In this way, actions can be restricted byAccessControlContext s different from the current one.

An AccessControlContext contains information about all the code executed since theAccessControlContext was instantiated, including the code location and the permissions the code isgranted by the policy. In order for an access control check to succeed, the policy must grant each code itemreferenced by the AccessControlContext the required permissions.

If the AccessControlContext provided to doAsPrivileged is null , then the action is notrestricted by a separate AccessControlContext . One example where this may be useful is in a server environment. A server may authenticate multiple incoming requests and perform a separate doAsoperation for each request. To start each doAs action "fresh," and without the restrictions of the currentserver AccessControlContext , the server can call doAsPrivileged and pass in a nullAccessControlContext .

Principals

As mentioned previously, Principal s may be associated with a Subject if authentication issuccessful. Principal s represent Subject identities, and must implement thejava.security.Principal and java.io.Serializable interfaces. The Subject section describes ways to update the Principal s associated with a Subject .

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 relatedto credentials: Refreshable and Destroyable .

Refreshable

The javax.security.auth.Refreshable interface provides the capability for a credential torefresh itself. For example, a credential with a particular time-restricted lifespan may implement thisinterface to allow callers to refresh the time period for which it is valid. The interface has two abstractmethods:
http://download.oracle.com/javase/1.4.2/docs/api/java/security/Principal.htmlhttp://download.oracle.com/javase/1.4.2/docs/api/java/io/Serializable.htmlhttp://download.oracle.com/javase/1.4.2/docs/api/java/io/Serializable.htmlhttp://download.oracle.com/javase/1.4.2/docs/api/java/io/Serializable.htmlhttp://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/JAASRefGuide.html#Subject%23Subjecthttp://download.oracle.com/javase/1.4.2/docs/api/javax/security/auth/Refreshable.htmlhttp://download.oracle.com/javase/1.4.2/docs/api/java/security/Principal.htmlhttp://download.oracle.com/javase/1.4.2/docs/api/java/io/Serializable.htmlhttp://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/JAASRefGuide.html#Subject%23Subjecthttp://download.oracle.com/javase/1.4.2/docs/api/javax/security/auth/Refreshable.html


11/22

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 performan AuthPermission("refreshCredential") security check to ensure the caller has permissionto refresh the credential.

Destroyable

The javax.security.auth.Destroyable interface provides the capability of destroying thecontents 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 onthis credential will result in an IllegalStateException being thrown. The method implementationshould perform an AuthPermission("destroyCredential") 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 LoginContext .2. The LoginContext consults a Configuration to load all of the LoginModule s

configured for that application.3. The application invokes the LoginContext 's login method.4. The login method invokes all of the loaded LoginModule s. Each LoginModule attempts to

authenticate the subject. Upon success, LoginModule s associate relevant Principal s andcredentials with a Subject object that represents the subject being authenticated.

5. The LoginContext returns the authentication status to the application.6. If authentication succeeded, the application retrieves the Subject from the LoginContext .

The authentication classes are described below.

LoginContext

The javax.security.auth.login.LoginContext class provides the basic methods used toauthenticate subjects, and provides a way to develop an application independent of the underlyingauthentication technology. The LoginContext consults a Configuration to determine the

authentication services, or LoginModule (s) , configured for a particular application. Therefore, differentLoginModule s can be plugged in under an application without requiring any modifications to theapplication itself.

LoginContext offers four constructors from which to choose:

public LoginContext(String name) throws LoginException;
http://download.oracle.com/javase/1.4.2/docs/api/javax/security/auth/Destroyable.htmlhttp://download.oracle.com/javase/1.4.2/docs/api/javax/security/auth/login/Configuration.htmlhttp://download.oracle.com/javase/1.4.2/docs/api/javax/security/auth/login/LoginContext.htmlhttp://download.oracle.com/javase/1.4.2/docs/api/javax/security/auth/login/Configuration.htmlhttp://download.oracle.com/javase/1.4.2/docs/api/javax/security/auth/login/Configuration.htmlhttp://download.oracle.com/javase/1.4.2/docs/api/javax/security/auth/login/Configuration.htmlhttp://download.oracle.com/javase/1.4.2/docs/api/javax/security/auth/spi/LoginModule.htmlhttp://download.oracle.com/javase/1.4.2/docs/api/javax/security/auth/spi/LoginModule.htmlhttp://download.oracle.com/javase/1.4.2/docs/api/javax/security/auth/spi/LoginModule.htmlhttp://download.oracle.com/javase/1.4.2/docs/api/javax/security/auth/spi/LoginModule.htmlhttp://download.oracle.com/javase/1.4.2/docs/api/javax/security/auth/spi/LoginModule.htmlhttp://download.oracle.com/javase/1.4.2/docs/api/javax/security/auth/Destroyable.htmlhttp://download.oracle.com/javase/1.4.2/docs/api/javax/security/auth/login/Configuration.htmlhttp://download.oracle.com/javase/1.4.2/docs/api/javax/security/auth/login/LoginContext.htmlhttp://download.oracle.com/javase/1.4.2/docs/api/javax/security/auth/login/Configuration.htmlhttp://download.oracle.com/javase/1.4.2/docs/api/javax/security/auth/spi/LoginModule.html


12/22

public LoginContext(String name, Subject subject) throwsLoginException;

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 LoginContextas an index into the login Configuration to determine which LoginModule s are configured for theapplication instantiating the LoginContext . Constructors that do not take a Subject as an input

parameter instantiate a new Subject . Null inputs are disallowed for all constructors. Callers require anAuthPermission with target "createLoginContext." to instantiate a LoginContext . Here, refers to the name of the login configuration entry that the application references in the name

parameter for the LoginContext instantiation.

See the CallbackHandler section for information on what a CallbackHandler is and when you mayneed one.

Actual authentication occurs with a call to the following method:

public void login() throws LoginException;

When login is invoked, all of the configured LoginModule s are invoked to perform the authentication.If the authentication succeeded, the Subject (which may now hold Principal s, public credentials, and

private credentials) can be retrieved by using the following method:

public Subject getSubject();

To logout a Subject and remove its authenticated Principals and credentials, the following methodis provided:

public void logout() throws LoginException;

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

// let the LoginContext instantiate a new SubjectLoginContext lc = new LoginContext("entryFoo");try {

// authenticate the Subjectlc.login();System.out.println("authentication successful");

// get the authenticated SubjectSubject subject = lc.getSubject();

...

// all finished -- logoutlc.logout();

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

le.getMessage());
http://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/JAASRefGuide.html#CallbackHandler%23CallbackHandlerhttp://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/JAASRefGuide.html#CallbackHandler%23CallbackHandlerhttp://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/JAASRefGuide.html#CallbackHandler%23CallbackHandler


13/22

}

LoginModule

The LoginModule interface gives developers the ability to implement different kinds of authenticationtechnologies that can be plugged in under an application. For example, one type of LoginModule may

perform a username/password-based form of authentication. Other LoginModule s may interface tohardware devices such as smart cards or biometric devices.

Note: If you are an application writer, you do not need to understand the workings of LoginModule s. Allyou have to know is how to write your application and specify configuration information (such as in a loginconfiguration file) such that the application will be able to utilize the LoginModule specified by theconfiguration to authenticate the user.

If, on the other hand, you are a programmer who wishes to write a LoginModule implementing anauthentication technology, see the JAAS LoginModule Developer's Guide for detailed step-by-stepinstructions.

CallbackHandler

In some cases a LoginModule must communicate with the user to obtain authentication information.LoginModule s use a javax.security.auth.callback.CallbackHandler for this purpose. Applicationsimplement the CallbackHandler interface and pass it to the LoginContext , which forwards itdirectly to the underlying LoginModule s. A LoginModule uses the CallbackHandler both togather 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 CallbackHandler , underlyingLoginModules can remain independent of the different ways applications interact with users. For example, the implementation of a CallbackHandler for a GUI application might display a window tosolicit input from a user. On the other hand, the implementation of a CallbackHandler for a non-GUItool might simply prompt the user for input directly from the command line.

CallbackHandler is an interface with one method to implement:void handle(Callback[] callbacks)

throws java.io.IOException, UnsupportedCallbackException;

The LoginModule passes the CallbackHandler handle method an array of appropriateCallback s, for example a NameCallback for the user name and a PasswordCallback for the password,and the CallbackHandler performs the requested user interaction and sets appropriate values in theCallback s. For example, to process a NameCallback , the CallbackHandler may prompt for aname, retrieve the value from the user, and call the NameCallback 's setName method to store thename.

The CallbackHandler documentation has a lengthy example not included in this document that readersmay want to examine.

Callback

The javax.security.auth.callback package contains the Callback interface as well as severalimplementations. LoginModule s may pass an array of Callback s directly to the handle method of aCallbackHandler.
http://download.oracle.com/javase/1.4.2/docs/api/javax/security/auth/spi/LoginModule.htmlhttp://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/JAASLMDevGuide.htmlhttp://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/JAASLMDevGuide.htmlhttp://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/JAASLMDevGuide.htmlhttp://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/JAASLMDevGuide.htmlhttp://download.oracle.com/javase/1.4.2/docs/api/javax/security/auth/callback/CallbackHandler.htmlhttp://download.oracle.com/javase/1.4.2/docs/api/javax/security/auth/callback/CallbackHandler.htmlhttp://download.oracle.com/javase/1.4.2/docs/api/javax/security/auth/callback/NameCallback.htmlhttp://download.oracle.com/javase/1.4.2/docs/api/javax/security/auth/callback/NameCallback.htmlhttp://download.oracle.com/javase/1.4.2/docs/api/javax/security/auth/callback/PasswordCallback.htmlhttp://download.oracle.com/javase/1.4.2/docs/api/javax/security/auth/callback/PasswordCallback.htmlhttp://download.oracle.com/javase/1.4.2/docs/api/javax/security/auth/callback/PasswordCallback.htmlhttp://download.oracle.com/javase/1.4.2/docs/api/javax/security/auth/callback/CallbackHandler.htmlhttp://download.oracle.com/javase/1.4.2/docs/api/javax/security/auth/callback/package-summary.htmlhttp://download.oracle.com/javase/1.4.2/docs/api/javax/security/auth/callback/package-summary.htmlhttp://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/JAASRefGuide.html#CallbackHandler%23CallbackHandlerhttp://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/JAASRefGuide.html#CallbackHandler%23CallbackHandlerhttp://download.oracle.com/javase/1.4.2/docs/api/javax/security/auth/spi/LoginModule.htmlhttp://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/JAASLMDevGuide.htmlhttp://download.oracle.com/javase/1.4.2/docs/api/javax/security/auth/callback/CallbackHandler.htmlhttp://download.oracle.com/javase/1.4.2/docs/api/javax/security/auth/callback/NameCallback.htmlhttp://download.oracle.com/javase/1.4.2/docs/api/javax/security/auth/callback/PasswordCallback.htmlhttp://download.oracle.com/javase/1.4.2/docs/api/javax/security/auth/callback/CallbackHandler.htmlhttp://download.oracle.com/javase/1.4.2/docs/api/javax/security/auth/callback/package-summary.htmlhttp://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/JAASRefGuide.html#CallbackHandler%23CallbackHandler


14/22

Please consult the various Callback 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 Policy abstract class and the authorization-specific classes AuthPermission andPrivateCredentialPermission are described below.

Policy

The java.security.Policy class is an abstract class for representing the system-wide accesscontrol policy. The Policy API was upgraded in the J2SDK, v 1.4 to support Principal -based queries.

As a default, the J2SDK provides a file-based subclass implementation, which was upgraded to supportPrincipal -based grant entries in policy files.

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

AuthPermission

The javax.security.auth.AuthPermission class encapsulates the basic permissions requiredfor JAAS. An AuthPermission 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 java.security.Permission class), anAuthPermission has two public constructors:

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

The first constructor creates a new AuthPermission with the specified name. The second constructor also creates a new AuthPermission object with the specified name, but has an additional actionsargument which is currently unused and should be null. This constructor exists solely for the Policyobject to instantiate new Permission objects. For most other code, the first constructor is appropriate.

Currently the AuthPermission object is used to guard access to the Policy , Subject ,LoginContext , and Configuration objects. Please refer to the AuthPermission javadocs for the listof valid names that are supported.

PrivateCredentialPermission
http://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/JAASRefGuide.html#LoginContext%23LoginContexthttp://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/JAASRefGuide.html#LoginContext%23LoginContexthttp://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/JAASRefGuide.html#Subject%23Subjecthttp://download.oracle.com/javase/1.4.2/docs/api/java/security/Policy.htmlhttp://download.oracle.com/javase/1.4.2/docs/api/java/security/Principal.htmlhttp://download.oracle.com/javase/1.4.2/docs/guide/security/PolicyFiles.htmlhttp://download.oracle.com/javase/1.4.2/docs/guide/security/PolicyFiles.htmlhttp://download.oracle.com/javase/1.4.2/docs/guide/security/PolicyFiles.htmlhttp://download.oracle.com/javase/1.4.2/docs/api/javax/security/auth/AuthPermission.htmlhttp://download.oracle.com/javase/1.4.2/docs/api/java/security/Permission.htmlhttp://download.oracle.com/javase/1.4.2/docs/api/javax/security/auth/AuthPermission.htmlhttp://download.oracle.com/javase/1.4.2/docs/api/javax/security/auth/AuthPermission.htmlhttp://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/JAASRefGuide.html#LoginContext%23LoginContexthttp://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/JAASRefGuide.html#Subject%23Subjecthttp://download.oracle.com/javase/1.4.2/docs/api/java/security/Policy.htmlhttp://download.oracle.com/javase/1.4.2/docs/api/java/security/Principal.htmlhttp://download.oracle.com/javase/1.4.2/docs/guide/security/PolicyFiles.htmlhttp://download.oracle.com/javase/1.4.2/docs/guide/security/PolicyFiles.htmlhttp://download.oracle.com/javase/1.4.2/docs/api/javax/security/auth/AuthPermission.htmlhttp://download.oracle.com/javase/1.4.2/docs/api/java/security/Permission.htmlhttp://download.oracle.com/javase/1.4.2/docs/api/javax/security/auth/AuthPermission.html


15/22

The javax.security.auth.PrivateCredentialPermission class protects access to aSubject '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.
http://download.oracle.com/javase/1.4.2/docs/api/javax/security/auth/PrivateCredentialPermission.htmlhttp://download.oracle.com/javase/1.4.2/docs/api/javax/security/auth/PrivateCredentialPermission.htmlhttp://download.oracle.com/javase/1.4.2/docs/api/javax/security/auth/PrivateCredentialPermission.html


16/22

JAAS Tutorials and Sample ProgramsThe 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

(sample_jaas.config ) 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 Principal interface. It is used by

SampleLoginModule.

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

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 canlearn how to do so by reading the JAAS LoginModule Developer's Guide .
http://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/tutorials/GeneralAcnOnly.htmlhttp://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/tutorials/GeneralAcnAndAzn.htmlhttp://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/tutorials/GeneralAcnAndAzn.htmlhttp://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/tutorials/GeneralAcnAndAzn.htmlhttp://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/tutorials/SampleAcn.javahttp://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/tutorials/SampleAzn.javahttp://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/tutorials/sample_jaas.confighttp://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/tutorials/sampleacn.policyhttp://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/tutorials/sampleazn.policyhttp://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/tutorials/SampleLoginModule.javahttp://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/tutorials/SamplePrincipal.javahttp://download.oracle.com/javase/1.4.2/docs/api/java/security/Principal.htmlhttp://download.oracle.com/javase/1.4.2/docs/api/java/security/Principal.htmlhttp://download.oracle.com/javase/1.4.2/docs/api/java/security/Principal.htmlhttp://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/JAASLMDevGuide.htmlhttp://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/JAASLMDevGuide.htmlhttp://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/tutorials/GeneralAcnOnly.htmlhttp://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/tutorials/GeneralAcnAndAzn.htmlhttp://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/tutorials/SampleAcn.javahttp://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/tutorials/SampleAzn.javahttp://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/tutorials/sample_jaas.confighttp://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/tutorials/sampleacn.policyhttp://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/tutorials/sampleazn.policyhttp://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/tutorials/SampleLoginModule.javahttp://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/tutorials/SamplePrincipal.javahttp://download.oracle.com/javase/1.4.2/docs/api/java/security/Principal.htmlhttp://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/JAASLMDevGuide.html


17/22

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

A number of JAAS-related settings can be configured in the java.security master security propertiesfile, which is located in the lib/security directory of the Java 2 runtime.

JAAS adds two new security properties to java.security :

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

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

policy.provider policy.url. n

Login Configuration Provider

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

The default JAAS login configuration implementation can be replaced by specifying the alternative provider class implementation in the login.configuration.provider property.

For example:

login.configuration.provider=com.foo.ConfigIf the Security property login.configuration.provider is not found, or is left unspecified, then itis 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

If you are using a login configuration implementation that expects the configuration information to bespecified in files (as does the default implementation from Sun Microsystems), the location of the loginconfiguration file(s) can be statically set by specifying their respective URLs in thelogin.config.url. n property. ' n' is a consecutively numbered integer starting with 1. If multipleconfiguration 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.configlogin.config.url.2=file:C:/users/foo/.foo.login.config


18/22

If the location of the configuration files is not set in the java.security properties file, and also is notspecified dynamically from the command line (via the -Djava.security.auth.login.configoption), JAAS attempts to load a default configuration from

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

Policy Provider

The default policy implementation can be replaced by specifying the alternative provider classimplementation in the policy.provider property.

For example:

policy.provider=com.foo.PolicyIf the Security property policy.provider is not found, or is left unspecified, then the Policy is set tothe 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 inthe auth.policy.url. 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.policypolicy.url.2=file:C:/users/foo/.foo.policy

If the location of the policy file(s) is not set in the java.security properties file, and is not specifieddynamically from the command line (via the -Djava.security.policy option), the access control

policy defaults to the same policy as that of the system policy file installed with the the J2SDK. That policyfile

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 java.security file provided with the Java 2 runtime, v 1.4. Examplesettings for JAAS-related properties are shown in bold. In this example, we leave the values provided in thedefault java.security file for the policy.provider , policy.url. n , andlogin.configuration.provider properties. The default java.security file also lists a valuefor the login.config.url. n property, but it is commented out. In the example below, it is notcommented.


19/22

## 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.=## This declares a provider, and specifies its preference# order . The preference order is the order in which providers are# searched for requested algorithms (when no specific provider is

# requested). The order is 1-based; 1 is the most preferred, followed# by 2, and so on.## 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.# 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.Sunsecurity.provider.2=com.sun.net.ssl.internal.ssl.Providersecurity.provider.3=com.sun.rsajca.Providersecurity.provider.4=com.sun.crypto.provider.SunJCEsecurity.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 platformsupports# it an entropy gathering device can be selected.


20/22

##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.sourcesetting.

## 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 theclass# 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.policy policy.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 inpolicy# files.policy.expandProperties=true

# whether or not we allow an extra policy to be passed on the commandline# with -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:#


21/22

system.scope=sun.security.provider.IdentityDatabase

## List of comma-separated packages that start with or equal this string# will cause a security exception to be thrown when# passed to checkPackageAccess unless the# corresponding RuntimePermission ("accessClassInPackage."+package) has# been granted.package.access=sun.

## List of comma-separated packages that start with or equal this string# 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=SunX509ssl.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# replaced, changing these values will produce non-functional# SocketFactory or ServerSocketFactory implementations.##ssl.SocketFactory.provider=#ssl.ServerSocketFactory.provider=


22/22

Appendix B: Example LoginConfigurations

Login configurations are located using the login.config.url.n security properties found in thejava.security file. For more information about this property and the location of thejava.security file, see Appendix A .

The default Configuration implementation, ConfigFile , gets its configuration information from loginconfiguration files. For details about the default login Configuration implementation provided with JAAS,

please consult the javadocs for the com.sun.security.auth.login.ConfigFile class.

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 application Login1 only has one configured LoginModule, SampleLoginModule . Therefore, anattempt by Login1 to authenticate a subject (user or service) will be successful if and only if theSampleLoginModule succeeds.

The authentication logic for the application Login2 is easier to explain with the table below. Note: therequired , sufficient , requisite , and optional flags are described in the Configuration

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.

Last update: August 8, 2001
http://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/JAASRefGuide.html#AppendixA%23AppendixAhttp://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/JAASRefGuide.html#AppendixA%23AppendixAhttp://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/spec/com/sun/security/auth/login/ConfigFile.htmlhttp://download.oracle.com/javase/1.4.2/docs/api/javax/security/auth/login/Configuration.htmlhttp://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/JAASRefGuide.html#AppendixA%23AppendixAhttp://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/spec/com/sun/security/auth/login/ConfigFile.htmlhttp://download.oracle.com/javase/1.4.2/docs/api/javax/security/auth/login/Configuration.html

Documents

JavaTM Authentication and Authorization Service