Download Support Readiness Document Java Authentication and

Support Readiness Document
Java Authentication and
Authorization Service 1.0
Sun Microsystems, Inc.
Java Software
Support Readiness Document
Java Authentication and
Authorization Service 1.0
Sun Microsystems, Inc.
901 San Antonio Road
Palo Alto, CA 94303
U.S.A.
Version: 1.0
Release Date: February 22, 2000
 1999 by Sun Microsystems, Inc.—Printed in USA.
901 San Antonio Road, Palo Alto, California 94303
All rights reserved. No part of this work covered by copyright may be duplicated by any
means—graphic, electronic or mechanical, including photocopying, or storage in an information
retrieval system—without prior written permission of the copyright owner.
RESTRICTED RIGHTS LEGEND: Use, duplication, or disclosure by the government is subject to
restrictions as set forth in subparagraph (c)(1)(ii) of the Rights in Technical Data and Computer
Software clause at DFARS 252.227-7013 (October 1988) and FAR 52.227-19 (June 1987). The
product described in this manual may be protected by one or more U.S. patents, foreign patents,
and/or pending applications.
TRADEMARKS: Java, 100% Pure Java, Solaris, and Java Naming and Directory Interface are
trademarks of Sun Microsystems, Inc. Solaris SPARC (Platform Edition) is a trademark of Sun
Microsystems, Inc. All SPARC trademarks are used under license and are trademarks or
registered trademarks of SPARC International, Inc. in the United States and other countries.
Products bearing SPARC trademarks are based upon an architecture developed by Sun
Microsystems, Inc. UNIX is a registered trademark in the United States and other countries,
exclusively licensed through X/Open Company, Ltd.
Sun Microsystems, Inc.
901 San Antonio Road
Palo Alto, CA 94303
U.S.A.
Table of Contents
Preface iii
1.0 Java Authentication and Authorization Service Overview
1
1.1 Pluggable Authentication Module 1
1.2 Features of Java Authentication and Authorization Service 1
1.3 Benefits of Using Java Authentication and Authorization
Service 2
1.4 Localization and Internationalization 2
2.0 Product Distribution and Licensing 2
3.0 Requirements and Dependencies
3
3.1 Disk Space Needed to Install Java Authentication and Authorization
Service 3
3.2 Operating Environments and Versions Supported 3
3.3 Recommended System Configuration 4
3.4 Product Dependencies 4
3.5 Versions 4
4.0 Downloading Java Authentication and Authorization
Service 5
4.1 Name and Size of Download Files
4.2 Steps to Download 6
5
5.0 Installing Java Authentication and Authorization Service
6
5.1 Pre-Installation Considerations 6
5.2 Installing the Java Authentication and Authorization Service
Components 6
5.2.1 Installing the Java Authentication and Authorization Service Class
Libraries 6
5.2.2 Installing the Java Authentication and Authorization Service Sample
Authentication Modules 7
5.2.3 Installing the Javadocs 8
5.2.4 Testing the Installation 9
SUN MICROSYSTEMS, INC.
i
Table of Contents
5.3 Directories Created at Installation 9
5.3.1 Directories Created When Installing the Class Libraries 9
5.3.2 Directories Created When Installing the Sample Authentication
Modules 10
5.3.3 Directories Created When Installing the Javadocs 10
6.0 Uninstalling JAAS
10
7.0 Administering and Configuring JAAS
8.0 Key Files
11
12
9.0 Using JAAS
13
9.1 Java Authentication and Authorization Service API Core
Classes 14
9.1.1 Common Classes 14
9.1.1.1 Subject Class 14
9.1.1.2 Principal Class 15
9.1.1.3 Credential Class 15
9.1.2 Authentication Classes and Interfaces 15
9.1.2.1 LoginContext Class 16
9.1.2.2 LoginModule Interface 16
9.1.2.3 CallbackHandler Interface 16
9.1.2.4 Callback Interface 17
9.1.3 Authorization Classes 17
9.1.3.1 Policy Abstract Class 17
9.1.3.2 AuthPermission Class 17
9.1.3.3 PrivateCredentialPermission Class
9.2 Java Authentication
Programs 18
10.0 Troubleshooting
and
18
Authorization
Service
Sample
18
10.1 Common Causes of Security Exceptions 18
10.2 Common User Questions 19
10.2.1 Published Questions and Answers 19
10.2.2 Additional Developer Questions 19
10.2.2.1 Determining Whether Security Policy Was Parsed Correctly and
Is in Effect 19
10.2.2.2 Code Runs When Expecting a Security Exception 20
10.2.2.3 Security Exception Occurs When Not Expected 20
10.2.2.4 Determining What Code Is Causing a Security Exception 21
10.3 Troubleshooting Utilities
11.0 Reference Information
11.1
11.2
11.3
11.4
21
21
Product Information 21
Frequently Asked Questions 22
Related Documentation 22
Bug Reports, Questions, and Feedback 22
SUN MICROSYSTEMS, INC.
ii
Preface
This document provides Support Readiness information for Java Authentication and
Authorization Service 1.0. The goal of Support Readiness Documents (SRDs) is to help
support engineers prepare to support Java Software products. SRDs are not designed to
provide comprehensive product training (see the product documentation or Sun
Education for this). Instead, they focus on issues immediately relevant to support, such
as installation, configuration, and common user problems.
Document Format Options: PDF and PostScript
The Java Authentication and Authorization Service SRD can be viewed in PostScript or
PDF format. The PDF version of the document allows navigation via a table of contents
frame, and the benefit of live cross references and web links. Text that is underlined and
in blue, such as the URL in this paragraph, are clickable links in the PDF version of the
document. (Note: page numbers in the PDF document refer to printed pages, and will
not coincide with the page numbers in the PDF reader status bar.) Although the blue
color and underlining appear in the PostScript version, there are no live links when
viewing that version.
Typographic Conventions
This document uses the following type conventions:
• The names of commands, files, Java™ objects, Java classes, and directories are
shown in regular monospace font.
• Text that is a placeholder to be replaced with a real name or value appears in italic
type; for example: % unzip jsdt-1.4.zip -d destination directory.
• Text that you type, when shown alongside computer output such as a command
prompt, is shown in bold monospace font. The marker "prompt>," in regular
monospace font, represents the actual command prompt you would see on your
screen, which may vary depending on your specific environment, shell, or platform.
For example: Solaris prompt> ls -l.
• The names of menu items, buttons, windows, and keyboard keys appear in regular
font with initial capitals, such as the Enter key.
• URLs that are clickable web links in the PDF version of the document are shown in
blue, underlined monospace font, as in http://java.sun.com. Although the blue
color and underlining appears in the PostScript version, there are no live links when
viewing that version.
SUN MICROSYSTEMS, INC.
iii
Preface
• URLs that are not clickable web links are shown in regular monospace font, such as
jsdt://stard:5555/socket/Session/chatSession.
• Cross-references to other sections of the document are shown in regular font but are
blue and underlined, as in, See Section 1.0, “JSDT Overview.” In the PDF version of
the document, these are clickable links to the indicated section. Although the blue
color and underlining appears in the PostScript version, there are no live links when
viewing that version.
• New terms and book titles appear in italic type.
SUN MICROSYSTEMS, INC.
iv
Java Authentication and Authorization
Service 1.0
1.0 Java Authentication and Authorization Service
Overview
The Java™ Authentication and Authorization Service (JAAS) version 1.0 is a Java
package that enables services to authenticate users and enforce access controls upon
them. It implements a Java version of the standard Pluggable Authentication Module
(PAM) framework, and extends the access control architecture of the Java 2 Platform to
support user-based authorization.
The product page for JAAS is http://java.sun.com/products/jaas/.
1.1 Pluggable Authentication Module
PAM is a flexible authentication framework that allows system administrators to associate authentication services with applications. The architecture enables applications to
remain independent from the underlying authentication services. As new authentication
services become available, or current services are updated, system administrators can
easily plug them in without having to modify or recompile existing applications. PAM
was originally developed in C for Solaris 2.6, and has become standardized and ported
to a number of UNIX platforms, including HP-UX, AIX, and Linux.
Additional documentation on PAM can be found at
http://www.sun.com/software/solaris/pam/.
1.2 Features of Java Authentication and Authorization Service
JAAS provides the following features:
• 100% Pure Java™ implementation
• Pluggable Authentication Module (PAM) framework implementation for authenticating users
• Single sign-on support
SUN MICROSYSTEMS, INC.
1 of 22
Product Distribution and Licensing
• Flexible access control policy for user-based, group-based, and role-based authorization
1.3 Benefits of Using Java Authentication and Authorization Service
The Java 2 Software Development Kit (SDK) version 1.3 provides a means to enforce
access controls based on where code came from and who digitally signed it. The need
for such access controls derives from the distributed nature of the Java platform, where,
for instance, a remote applet may be downloaded over a public network and then run
locally.
When you download digitally signed code, you can verify its authenticity and integrity.
The digital signature allows you to verify the identity of the code signer and also allows
you to ensure that the code was not modified en route over the network. Additional
information on digital signatures, as well as information on digital signature support in
the Java 2 platform, can be found in the Java 2 security tutorial at
http://java.sun.com/docs/books/tutorial/security1.2/index.html.
While the Java 2 platform can provide access controls that restrict code based on where
the code came from and who digitally signed it, Java 2 lacks the means to enforce access
controls that restrict code based on who runs it. To provide this type of access control,
the Java 2 security architecture requires additional support for authentication (determining who is actually running the code) and extensions to the existing authorization components to enforce new access controls based on who was authenticated. The JAAS
framework augments the Java 2 platform with this support.
1.4 Localization and Internationalization
JAAS 1.0 is I18N compliant. The JAAS ResourceBundle, located in
com.sun.security.auth.Resources, contains the default English translations for
all output and error messages.
The only portions of the JAAS 1.0 release that are not I18N compliant are:
• Sample code (applications and authentication modules)
• Debugging output
2.0 Product Distribution and Licensing
JAAS is available for download at no charge from
http://java.sun.com/products/jaas/.
JAAS software and documentation is free to use for commercial programming, but not
to redistribute. For more information on licensing, please refer to
http://java.sun.com/nav/business/.
At this point, the source code is not available for licensing. If there is a large demand for
the source code, it may be made available under a yet-to-be-determined licensing agreement.
SUN MICROSYSTEMS, INC.
2 of 22
Requirements and Dependencies
Since JAAS is an authentication framework, not a cryptographic framework, it is
exportable outside the US and Canada.
3.0 Requirements and Dependencies
3.1 Disk Space Needed to Install Java Authentication and Authorization
Service
You can install one or more of the four JAAS components:
• JAAS 1.0 class libraries (binary code) and sample code (source and binary code)
• Javadocs for the JAAS 1.0 API specification
• Sample authentication modules (binary) using:
• Java Naming and Directory Interface™ (JNDI)
• Solaris™ Operating Environment
• Windows NT
• Javadocs for the sample authentication modules
The sample authentication modules provide useful examples for developers implementing their own modules. While the sample modules can be used in an actual live environment for authentication, they are intended to be used for reference only.
Each component is installed separately. Table 1, “Disk Space Needed to Install JAAS
Components,” lists the disk space required to install each component.
TABLE 1.
Disk Space Needed to Install JAAS Components
Component
Disk Space Required for Install
JAAS class libraries
300 KB
Javadocs for the JAAS class libraries
935 KB
Sample authentication modules
100 KB
Javadocs for the sample authentication modules
180 KB
3.2 Operating Environments and Versions Supported
JAAS was developed and tested on the following platforms:
• Solaris 2.X on SPARC
• Solaris 2.X on Intel
• Win32 (Windows 95, 98, and NT)
Since JAAS is 100% Pure Java, it should run on any platform to which the Java 2 Platform has been ported. For a list of platforms to which Java 2 has been ported, see
http://java.sun.com/cgi-bin/java-ports.cgi.
SUN MICROSYSTEMS, INC.
3 of 22
Requirements and Dependencies
3.3 Recommended System Configuration
The recommended system configuration for JAAS is the same as the configuration recommended for the Java 2 Platform.
• Solaris on SPARC minimum configuration
• SPARCstation™ 5
• 48 MB RAM
• 100 MB available hard disk space
• Solaris on Intel minimum configuration
• Pentium 150
• 48 MB RAM
• 100 MB available hard disk space
• Win32 minimum configuration
• Pentium 150
• 48 MB RAM
• 100 MB available hard disk space
3.4 Product Dependencies
JAAS is a standard extension of the Java 2 platform. In a development environment, you
must have the Java 2 SDK version 1.3 or higher installed before you install JAAS. When
running an application that uses JAAS, you must have either the Java 2 SDK version 1.3
or higher, or the Java 2 Runtime Environment (J2RE) version 1.3 or higher installed
before you install JAAS.
3.5 Versions
This is the first release of JAAS. There was a beta release of JAAS in November 1999.
The differences between the official release and the beta versions of JAAS 1.0 are listed
in the README file, located at
http://java.sun.com/products/jaas/README.html.
The changes made to the beta release for the FCS version are as follows:
• javax.security.auth:
• SubjectDomainCombiner.getSubject – Has a new security check.
• Policy.getPermissions – No longer throws java.io.IOException.
• Policy.refresh – No longer throws java.io.IOException.
• AuthPermission(getPrivateCredentials) – Removed.
• PrivateCredentialPermission – Has two new methods:
getCredentialClass and getPrincipals.
• javax.security.auth.login:
• LoginContext – Constructors have new security checks.
SUN MICROSYSTEMS, INC.
4 of 22
Downloading Java Authentication and Authorization Service
• LoginContext – Binds the provided application CallbackHandler with the
caller’s AccessControlContext.
• LoginContext – Invokes LoginModules inside a
AccessController.doPrivileged block. (LoginModules should not call
doPrivileged themselves.)
• LoginContext – Class is no longer final.
• Configuration.getAppConfigurationEntry – No longer throws
java.io.IOException.
• Configuration.refresh – No longer throws java.io.IOException.
• com.sun.security.auth:
• X500Principal – New class created.
• PolicyFile – Supports grant statements with wildcard (*) Principal entries.
• PolicyFile – Supports additional self behavior for
PrivateCredentialPermissions.
For more detailed information on any of the above API changes, please refer to the javadocs for the respective classes at
http://java.sun.com/security/jaas/apidoc/index.html.
4.0 Downloading Java Authentication and
Authorization Service
4.1 Name and Size of Download Files
JAAS is packaged as four downloadable items listed in Section 3.1, “Disk Space
Needed to Install Java Authentication and Authorization Service.” Except for the sample authentication modules, the download file for each component is the same for all
platforms. Table 2, “Name and Size of Download Files,” gives the disk space required to
download each of the four components of JAAS.
TABLE 2.
Name and Size of Download Files
Component
File Name
Disk Space
Required for
Download
JAAS class libraries
jaas1_0.zip
135 KB
Javadocs for the JAAS class libraries
jaas1_0-doc.zip
205 KB
Sample authentication modules for
Solaris on SPARC
jaasmod1_0-solsparc.zip
30 KB
Sample authentication modules for
Solaris on Intel
jaasmod1_0-solx86.zip
30 KB
SUN MICROSYSTEMS, INC.
5 of 22
Installing Java Authentication and Authorization Service
TABLE 2.
Name and Size of Download Files
Component
File Name
Disk Space
Required for
Download
Sample authentication modules for Windows
jaasmod1_0-win.zip
50 KB
Javadocs for the sample authentication
Modules
jaasmod1_0-doc.zip
60 KB
4.2 Steps to Download
To download any JAAS component, access
http://java.sun.com/products/jaas/. Choose the component you want to
download and follow the instructions. When downloading the sample authentication
modules, you must choose the appropriate platform.
You can separately download the javadocs for the JAAS class libraries and the sample
authentication modules, or you can read them online from
http://java.sun.com/security/jaas/apidoc/index.html or
http://java.sun.com/security/jaas/jaasmod/apidoc/index.html.
5.0 Installing Java Authentication and Authorization
Service
5.1 Pre-Installation Considerations
Before you install JAAS, you must have one of the following installed on your system:
• Java 2 SDK version 1.3 or higher
• J2RE version 1.3 or higher
5.2 Installing the Java Authentication and Authorization Service Components
5.2.1
Installing the Java Authentication and Authorization Service Class Libraries
To install the JAAS class libraries, do the following:
1. Download the JAAS class libraries download file, jaas1_0.zip, as described in
Section 4.0, “Downloading Java Authentication and Authorization Service.” You can
save the downloaded file anywhere on your local disk.
2. Uncompress and extract the downloaded file.
On Solaris, type:
% unzip jaas1_0.zip
On Windows, use the WinZip utility to uncompress the download file.
SUN MICROSYSTEMS, INC.
6 of 22
Installing Java Authentication and Authorization Service
Uncompressing the file creates a directory named jaas1_0 with two subdirectories,
doc and lib. For more information on the files and directories created by the installation, see Section 5.3.1, “Directories Created When Installing the Class Libraries.”
3. JAAS 1.0 is supplied as an extension to the Java 2 platform. You can install JAAS
either as an “installed extension” or as a “bundled extension.”
The lib subdirectory extracted in the previous step contains the extension file,
jaas.jar. You can install this file in the JRE (“installed extension”) or bundle it
with your application (“bundled extension”). For more information on extensions,
please see http://java.sun.com/products/jdk/1.2/docs/guide/
extensions/index.html.
• Installed Extension
For more information on how to install the jaas.jar extension file in the JRE,
please reference the “Installed Extensions” section in the extensions documentation at: http://java.sun.com/products/jdk/1.2/docs/
guide/extensions/spec.html#installed.
• Bundled Extension
For more information on how to bundle the jaas.jar extension file with your
application or applet, please reference the “Bundled Extensions” section in the
extensions documentation at: http://java.sun.com/products/
jdk/1.2/docs/guide/extensions/spec.html#bundled.
5.2.2
Installing the Java Authentication and Authorization Service Sample
Authentication Modules
To install the JAAS sample authentication modules, do the following:
1. Download the JAAS sample authentication modules download file,
jaasmod1_0.zip, as described in Section 4.0, “Downloading Java Authentication
and Authorization Service.” You can save the downloaded file anywhere on your
local disk.
2. Uncompress and extract the downloaded file.
On Solaris, type:
% unzip jaasmod1_0.zip
On Windows, use the WinZip utility to uncompress the download file.
Uncompressing the file creates a directory named jaasmod1_0 with two subdirectories, doc and lib. For more information on the files and directories created by the
installation, see Section 5.3.2, “Directories Created When Installing the Sample
Authentication Modules.”
3. You can treat the jaasmod.jar file as untrusted code or as fully trusted code.
• When treating jaasmod.jar as untrusted code, place it in your application’s
CLASSPATH. For example, on Windows, if the sample authentication modules
were downloaded into C:\jaasmod1.0, the CLASSPATH could be set with the
command line:
> java -classpath <appClassPath>;C:\jaasmod1.0ıib\jaasmod.jar <app>
where <appClassPath> represents the directories where the application classes
reside and <app> represents the class name of the application to be run.
SUN MICROSYSTEMS, INC.
7 of 22
Installing Java Authentication and Authorization Service
• When treating jaasmod.jar as fully trusted code, install jaasmod.jar as
either an “installed extension” or as a “bundled extension” as described in Step 3
of Section 5.2.1, “Installing the Java Authentication and Authorization Service
Class Libraries.”
4. Native libraries that support the Java Authentication Module implementations also
reside in the lib directory. The native libraries perform operating system–level calls
and other operations that require non-Java implementations. When using the sample
authentication modules, you must be sure that the native libraries are available to the
modules.
You can make the native libraries available to the sample authentication modules
either by copying them into the appropriate directory in the Java 2 SDK or J2RE or
by setting them at the command line. Table 3, “Native Libraries for the Java Authentication Module,” identifies the libraries that should be copied and the directories
into which they should be copied.
TABLE 3.
Native Libraries for the Java Authentication Module
Platform
Library
Destination Directory
Solaris/SPARC
libsolaris.so
lib/sparc
Solaris/Intel
libsolaris.so
lib/i386
Win32
nt.dll
bin
If you prefer to reference the native libraries at the command line, you may set the
Java system property java.library.path to the proper value when you run your
Java application. For example, on Solaris:
% java -Djava.library.path=jaasmod1_0/lib <yourApp>
where <yourApp> is the class name of your application.
On Windows:
> java -Djava.library.path=jaasmod1_0\lib <yourApp>
5. Before you can use the JndiLoginModule included in the sample authentication
modules, you must first download and install the Java Naming and Directory Interface (JNDI) 1.2 or later. JNDI is available from
http://java.sun.com/products/jndi/. You must install JNDI either as an
installed extension or as a bundled extension, as described in Step 3 of Section 5.2.1,
“Installing the Java Authentication and Authorization Service Class Libraries.”
5.2.3
Installing the Javadocs
To install the javadocs either for the JAAS class libraries or for the sample authentication modules, do the following:
1. Download the javadocs download file, either jaas-doc.zip or
jaasmod1_0-doc.zip, as described in Section 4.0, “Downloading Java Authentication and Authorization Service.” You can save the downloaded file anywhere on
your local disk.
2. Uncompress and extract the downloaded file.
On Solaris, type:
SUN MICROSYSTEMS, INC.
8 of 22
Installing Java Authentication and Authorization Service
% unzip <download_file>.zip
where <download_file> is either jaas1_0-doc or jaasmod1_0.
On Windows, use the WinZip utility to uncompress the download file.
Uncompressing the file creates a directory named either jaas1_0-doc or
jaasmod1_0-doc, with two subdirectories named apidoc and images. By
default, the directory is created in the directory where downloaded file resides.
3. The starting point for viewing the javadocs is
jaas1_0-doc/apidoc/index.html or
jaasmod1_0-doc/apidoc/index.html.
5.2.4
Testing the Installation
You can test the JAAS installation by attempting to run the sample program provided in
the doc/samples directory created when you installed the JAAS class libraries. Directions for running the sample program are located at
http://java.sun.com/security/jaas/doc/api.html. If the sample program
runs without throwing any security exceptions, then you can assume that JAAS is
installed properly.
The sample program is designed to demonstrate how JAAS can be used to enforce
access controls on an authenticated user. If configured and run properly, the sample program will not throw any security exceptions. This is because the proper permissions
have been granted in the sample policy files. However, when experimenting with the
program, you may remove any granted permissions from the sample security policies to
see the various security exceptions that would be thrown.
If no permissions are granted in the security policies, the security exceptions should
occur when doing any of the following:
•
•
•
•
Instantiating a LoginContext
Invoking the Subject.doAs method
Accessing the system properties java.home and user.home
Reading the file foo.txt
5.3 Directories Created at Installation
5.3.1
Directories Created When Installing the Class Libraries
When installing the JAAS class libraries, the directory jaas1_0 is created with two
subdirectories, doc and lib. By default, the jaas1_0 directory is created in the directory where the downloaded file resides.
The doc directory contains:
•
•
•
•
•
A README file
Installation instructions
License information
Copyright information
JAAS sample program (located in the samples subdirectory)
SUN MICROSYSTEMS, INC.
9 of 22
Uninstalling JAAS
The lib directory contains:
• The JAAS class implementation, bundled in the jaas.jar file
The JAAS API developer’s guide, located at
http://java.sun.com/security/jaas/doc/api.html, contains instructions
for running a sample JAAS program.
Note: No javadocs are included with this install. To obtain the javadocs, you must
download them separately from http://java.sun.com/products/jaas/.
5.3.2
Directories Created When Installing the Sample Authentication Modules
When installing the JAAS sample authentication modules, the directory jaasmod1_0 is
created with two subdirectories, doc and lib. By default, the jaasmod1_0 directory is
created in the directory where the downloaded file resides.
The doc directory contains:
•
•
•
•
A README file
Installation instructions
Licensing information
Copyright information
The lib directory contains:
• The sample authentication module implementations, bundled in the jaasmod.jar
file
• The native libraries used by the modules
Note: No javadocs are included with this install. To obtain the javadocs, you must
download them separately from http://java.sun.com/products/jaas/.
5.3.3
Directories Created When Installing the Javadocs
When installing the javadocs for the JAAS class modules, the directory jaas1_0-doc
is created with two subdirectories, apidoc and images. When installing the javadocs
for the sample authentication modules, the directory jaasmod1_0-doc is created with
two subdirectories, apidoc and images. By default, the directory is created in the
directory where the downloaded file resides.
6.0 Uninstalling JAAS
To uninstall the JAAS components, do the following:
1. Remove the jaas1_0 directory from your local disk. For example, on Solaris, type:
% rm -rf jaas1_0
2. If you installed the sample authentication modules, remove the jaasmod1_0 direc-
tory as well.
3. Remove the jaas.jar file from your JRE if it is an installed extension, or from
your application if it is a bundled extension.
SUN MICROSYSTEMS, INC.
10 of 22
Administering and Configuring JAAS
4. If you installed the sample authentication modules, remove the jaasmod.jar files
and native libraries as well.
5. If you installed the javadocs, remove the javadocs directories.
7.0 Administering and Configuring JAAS
JAAS requires that security policies and login configurations be properly administered.
The JAAS security policy was designed to extend the existing Java 2 security policy in a
simple and consistent manner. If you are familiar with the existing Java 2 security policy, you should find the JAAS extensions to the Java 2 security policy relatively straightforward.
The JAAS API Developer’s Guide, located at
http://java.sun.com/security/jaas/doc/api.html, and the sample program in the doc/samples directory contain documentation and sample policies that
may be useful as a reference. Of special interest is Appendix A of the JAAS API Developer’s Guide, “JAAS Settings in the java.security Security Properties File,” available at http://java.sun.com/security/jaas/doc/api.html#AppendixA.
The specification for the JAAS policy is located in the javadocs for the following
classes:
• javax.security.auth.Policy –
http://java.sun.com/security/jaas/apidoc/javax/security/
auth/Policy.html
• com.sun.security.auth.PolicyFile –
http://java.sun.com/security/jaas/apidoc/com/sun/security/
auth/PolicyFile.html
For consistency, the JAAS login configuration is administered in a manner similar to the
policy files. The specification for the login configuration is located in the javadocs for
the following classes:
• javax.security.auth.login.Configuration –
http://java.sun.com/security/jaas/apidoc/javax/security/
auth/login/Configuration.html
• com.sun.security.auth.login.ConfigFile –
http://java.sun.com/security/jaas/apidoc/com/sun/security/
auth/login/ConfigFile.html
If you are unfamiliar with Java 2 security policies, the following sequence should help
you get started:
1. Read and master the Java 2 security tutorial located at
http://java.sun.com/docs/books/tutorial/security1.2/
index.html. The tutorial helps guide you through the process of developing code
and granting permissions to code using the Java 2 security architecture without
JAAS present.
SUN MICROSYSTEMS, INC.
11 of 22
Key Files
2. Consult the policy section of the Java 2 security architecture overview document
located at http://java.sun.com/products/jdk/1.2/docs/guide/
security/PolicyFiles.html. This document describes the Java 2 security policy specification, and includes more detailed information on the Java 2 security policy syntax, as well as details regarding Java 2 policy configuration. Keep in mind
that this document is specific to the Java 2 security architecture without JAAS.
3. Consult the specification for the JAAS security policy to understand the new extensions defined by JAAS. The specification is located in the javadocs for the classes:
• javax.security.auth.Policy –
http://java.sun.com/security/jaas/apidoc/javax/security/
auth/Policy.html
• com.sun.security.auth.PolicyFile –
http://java.sun.com/security/jaas/apidoc/com/sun/security/
auth/PolicyFile.html
8.0 Key Files
JAAS relies on the JAAS security policy file and the JAAS login configuration file. The
purpose of the security policy is to grant permissions to code running as a particular
entity, such as a user or a group of users. The permissions are required for the user either
to access sensitive information such as files, or to perform security-sensitive operations
such as connecting to hosts on the network. The ability to protect sensitive resources
based on user information represents the main contribution of JAAS to the Java platform.
The purpose of the login configuration is to specify the technologies used to authenticate the user. Different technologies provide different levels of trust. For example, while
one technology might prompt for a name and password, another technology might verify a fingerprint. Obviously, a fingerprint is harder to steal or forge, and therefore more
trustworthy. The login configuration gives administrators the ability to choose and plug
in the appropriate authentication technologies sufficient to meet the security requirements of their respective environments.
JAAS does not require specific names or locations for the security policy file and login
configuration file. In fact, JAAS does not even require that the policy and configuration
reside in a file. The required way to implement, specify, and provide a policy and configuration is detailed in the javadocs for the classes:
• javax.security.auth.Policy –
http://java.sun.com/security/jaas/apidoc/javax/security/
auth/Policy.html
• javax.security.auth.login.Configuration –
http://java.sun.com/security/jaas/apidoc/javax/security/
auth/login/Configuration.html
The JAAS policy and configuration may reside anywhere, for example, in files, databases, or servers, and may be represented in any syntactic format. JAAS only requires
that the respective implementations conform to the policy and configuration APIs.
SUN MICROSYSTEMS, INC.
12 of 22
Using JAAS
To specify a particular policy implementation for use, set the value of the
auth.policy.provider security property in the Java security properties file to the
fully qualified name of the desired policy implementation class. The Java security properties file is located in the file <JAVA_HOME>/lib/security/java.security,
where <JAVA_HOME> refers to the directory where the SDK was installed.
To specify a particular configuration implementation, set the value of the
login.configuration.provider security property in the Java security properties
file to the fully qualified name of the desired policy implementation class.
If no particular policy or configuration implementations are specified, JAAS uses the
following file-based default implementations: for the policy implementation,
com.sun.security.auth.PolicyFile, and for the configuration,
com.sun.security.auth.login.ConfigFile.
Policy and configuration class implementations read and parse contents from actual policies and configurations. In the case of the default implementations, the respective contents are read from a file. The default implementations do not require the contents to
reside in a single file, nor do they require the actual files to reside in particular locations.
For more information on how to specify the location of single or multiple files containing policy and configuration information when using the default implementations,
please refer to the Javadocs for the classes:
• com.sun.security.auth.PolicyFile –
http://java.sun.com/security/jaas/apidoc/com/sun/security/
auth/PolicyFile.html
• com.sun.security.auth.login.ConfigFile –
http://java.sun.com/security/jaas/apidoc/com/sun/security/
auth/login/ConfigFile.html
The JAAS API Developer’s Guide, located at
http://java.sun.com/security/jaas/doc/api.html, contains additional
documentation for administering and configuring the security policy and login configuration files. In addition, the developer’s guide describes how to run the sample program
with the files.
9.0 Using JAAS
JAAS is a framework and API used by Java applications and services that require support for authenticating users, as well as for enforcing access controls upon those users.
The JAAS API Developer’s Guide and the JAAS LoginModule Developer’s Guide,
located at http://java.sun.com/security/jaas/doc/api.html and
http://java.sun.com/security/jaas/doc/module.html, are good starting
points for developers beginning to use JAAS. They provide a step-by-step natural progression through the prominent JAAS classes and APIs. Of course, the javadocs for the
JAAS classes represent the official specification, and they can be downloaded from the
SUN MICROSYSTEMS, INC.
13 of 22
Using JAAS
main JAAS product page at http://java.sun.com/products/jaas/ or viewed
online at http://java.sun.com/security/jaas/apidoc/index.html.
The JAAS FAQ, located at http://java.sun.com/security/jaas/faq.html,
contains answers to common design questions.
The remainder of this section summarizes the core classes of the JAAS API and briefly
describes the sample programs available with the JAAS download.
9.1 Java Authentication and Authorization Service API Core Classes
The JAAS infrastructure can be divided into two main components: an authentication
component and an authorization component. The core classes of the API are likewise
categorized into authentication classes and authorization classes, with a third category
of common classes that are shared by both components.
9.1.1
Common Classes
The JAAS common classes include the following:
• Subject class
• Principal class
• Credential class
The key JAAS class is Subject, which represents a grouping of related information for
a single entity such as a person. It encompasses the entity’s Principals, public credentials, and private credentials.
Note that JAAS uses the existing Java 2 java.security.Principal interface to
represent a Principal. Also note that JAAS does not introduce a separate credential interface or class. A credential, as defined by JAAS, may be any Object.
9.1.1.1
Subject Class
The key JAAS class is Subject, which represents a grouping of related information for a
single entity such as a person. It encompasses the entity’s Principals, public credentials,
and private credentials. Principals and credentials are described in the following paragraphs.
To authorize access to resources, applications first need to authenticate the source of the
request. The JAAS framework defines the term Subject to represent the source of a
request. A Subject may be any entity, such as a person or service. Once authenticated, a
Subject is populated with associated identities, or Principals. A Subject may have many
Principals. 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.
Sensitive credentials that require special protection, such as private cryptographic keys,
are stored within a private credential Set. Credentials intended to be shared, such as public key certificates or Kerberos tickets, are stored within a public credential Set. Different permissions are required to access and modify the various credential Sets.
SUN MICROSYSTEMS, INC.
14 of 22
Using JAAS
For more information and examples for using the JAAS Subject class, see the “Subject”
section of the JAAS API Developer’s Guide,
http://java.sun.com/security/jaas/doc/api.html#Subject.
9.1.1.2
Principal Class
Principals may be associated with a Subject. Principals represent Subject identities, and
must implement the java.security.Principal and java.io.Serializable
interfaces. The “Subject” section of the JAAS API Developer’s Guide,
http://java.sun.com/security/jaas/doc/api.html#Subject, describes
ways to update the Principals associated with a Subject.
9.1.1.3
Credential Class
Public and private credential classes are not part of the core JAAS class library. Any
Java class, therefore, can represent a credential. Developers, however, may elect to have
their credential classes implement the following two interfaces related to credentials:
• Refreshable – This interface provides the capability for a credential to refresh
itself. For example, a credential with a particular time-restricted life span may implement this interface to allow callers to refresh the time period for which it is valid.
• Destroyable – This interface provides the capability of destroying the contents
within a credential.
Note that JAAS does not introduce a separate credential interface or class. A credential,
as defined by JAAS, may be any Object.
For more information about using the JAAS Credential class, see the “Credentials” section of the JAAS API Developer’s Guide, available at
http://java.sun.com/security/jaas/doc/api.html#Credentials.
9.1.2
Authentication Classes and Interfaces
The JAAS authentication component provides the ability to reliably and securely determine who is currently executing Java code, regardless of whether the code is running as
an application, an applet, a bean, or a servlet.
To authenticate a Subject, the following steps are performed:
1. An application instantiates a LoginContext.
2. The LoginContext consults a Configuration to load all of the LoginModules config3.
4.
5.
6.
ured for that application.
The application invokes the LoginContext’s login method.
The login method invokes all of the loaded LoginModules. Each LoginModule
attempts to authenticate the Subject. Upon success, LoginModules associate relevant
Principals and credentials with the Subject.
The LoginContext returns the authentication status to the application.
If authentication succeeds, the application retrieves the authenticated Subject from
the LoginContext.
The JAAS authentication classes and interfaces include the following:
SUN MICROSYSTEMS, INC.
15 of 22
Using JAAS
•
•
•
•
9.1.2.1
LoginContext class
LoginModule interface
CallbackHandler interface
Callback interface
LoginContext Class
The LoginContext class provides the basic methods used to authenticate Subjects, and
provides a way to develop an application independent of the underlying authentication
technology. The LoginContext consults a Configuration to determine the authentication
services, or LoginModules, configured for a particular application. Therefore, different
LoginModules can be plugged in under an application without requiring any modifications to the application itself.
For more information and examples for using the JAAS LoginContext class, see the
“LoginContext” section of the JAAS API Developer’s Guide, available at
http://java.sun.com/security/jaas/doc/api.html#LoginContext.
9.1.2.2
LoginModule Interface
The LoginModule interface gives developers the ability to implement various kinds of
authentication technologies that can be plugged under an application. For example, one
type of LoginModule may perform a username/password–based form of authentication.
Other LoginModules may interface to hardware devices such as smart cards or biometric devices.
To instantiate a LoginModule, a LoginContext expects each LoginModule to provide a
public constructor that takes no arguments. Then, to initialize a LoginModule with the
relevant information, a LoginContext calls the LoginModule’s initialize method.
The provided subject is guaranteed to be non-null.
For more information and examples for using the JAAS LoginModule interface, see the
“LoginModule” section of the JAAS API Developer’s Guide, available at
http://java.sun.com/security/jaas/doc/api.html#LoginModule.
In addition, the LoginModule Developer’s Guide, available online at
http://java.sun.com/security/jaas/doc/module.html, provides detailed
step-by-step instructions for implementing LoginModules.
9.1.2.3
CallbackHandler Interface
In some cases, a LoginModule must communicate with the user to obtain authentication
information. LoginModules use a CallbackHandler for this purpose. Applications
implement the CallbackHandler interface and pass it to the LoginContext, which forwards it directly to the underlying LoginModules. LoginModules use the CallbackHandler both to gather input from users (such as a password or smart card pin number) or to
supply information to users (such as status information). By allowing the application to
specify the CallbackHandler, underlying LoginModules 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 to solicit input from a
SUN MICROSYSTEMS, INC.
16 of 22
Using JAAS
user. On the other hand, the implementation of a CallbackHandler for a non-GUI tool
might simply prompt the user for input directly from the command line.
For an example using the CallbackHandler interface, see the javadocs for
CallbackHandler at http://java.sun.com/security/jaas/apidoc/javax/
security/auth/callback/CallbackHandler.html.
9.1.2.4
Callback Interface
The javax.security.auth.callback package contains the Callback interface as
well as several implementations. LoginModules may pass an array of Callbacks directly
to the handle method of a CallbackHandler.
For more information on the Callback interface, see the javadocs for Callback at
http://java.sun.com/security/jaas/apidoc/javax/security/
auth/callback/Callback.html.
9.1.3
Authorization Classes
The JAAS authorization component supplements the existing Java 2 security framework
by providing the means to restrict the executing Java code from performing sensitive
tasks, depending on its code source (as is done in Java 2) and depending on who was
authenticated.
Upon successful authentication of a Subject, fine-grained access controls can be placed
upon that Subject by invoking the Subject.doAs methods. The permissions granted to
that Subject are configured in a JAAS Policy.
The JAAS authorization classes and interfaces include the following:
• Policy abstract class
• AuthPermission class
• PrivateCredentialPermission class
9.1.3.1
Policy Abstract Class
Policy is an abstract class for representing the system-wide JAAS access control policy.
As a default, JAAS provides a file-based subclass implementation, PolicyFile. For more
information and examples, see the “Policy” section of the JAAS API Developer’s Guide,
http://java.sun.com/security/jaas/doc/api.html#Policy.
For information on the PolicyFile class, see the javadocs for PolicyFile at
http://java.sun.com/security/jaas/apidoc/com/sun/security/
auth/PolicyFile.html.
9.1.3.2
AuthPermission Class
This class encapsulates the basic permissions required for JAAS. An AuthPermission
contains a name (also referred to as a target name) but no actions list.
SUN MICROSYSTEMS, INC.
17 of 22
Troubleshooting
For more information on the AuthPermission class, see the javadocs for
AuthPermission at http://java.sun.com/security/jaas/apidoc/javax/
security/auth/AuthPermission.html.
9.1.3.3
PrivateCredentialPermission Class
This class protects access to a Subject’s private credentials. For details about the PrivateCredentialPermission class, see the javadocs for PrivateCredentialPermission at
http://java.sun.com/security/jaas/apidoc/javax/security/auth/
PrivateCredentialPermission.html.
9.2 Java Authentication and Authorization Service Sample Programs
The download for the JAAS core class libraries includes a sample application, sample
LoginModule, sample login Configuration, and sample access control Policies. The
sample programs link together all of the important JAAS concepts, and provide a complete example for:
• Developing an application that uses JAAS to authenticate users
• Developing an authentication module that can be plugged under that application to
perform a specific type of authentication
• Administering a login configuration that controls the authentication module to be
plugged under the application
• Enforcing access controls upon the authenticated user
• Administering the Java 2 and JAAS security policies that controls the permissions
granted to the application, as well as to the authenticated user
Directions for running the sample program are located in the section “JAAS Sample
Program” of the API Developer’s Guide located at
http://java.sun.com/security/jaas/doc/api.html#Sample.
10.0 Troubleshooting
10.1 Common Causes of Security Exceptions
Default protection is provided to a number of security-sensitive JAAS APIs. Unless the
appropriate permissions are granted, callers will get a SecurityException when
attempting these method calls. All of the methods are protected by an
AuthPermission.
The following is a list of valid AuthPermissions and the method calls they permit.
This list is also located in the javadocs for
javax.security.auth.AuthPermission available online at
http://java.sun.com/security/jaas/apidoc/javax/security/auth/
AuthPermission.html.
• doAs – Allows the caller to invoke the Subject.doAs methods.
• doAsPrivileged – Allows the caller to invoke the Subject.doAsPrivileged
methods.
SUN MICROSYSTEMS, INC.
18 of 22
Troubleshooting
• getSubject – Allows for the retrieval of the Subject(s) associated with the current
Thread.
• getSubjectFromDomainCombiner – Allows for the retrieval of the Subject associated with the a SubjectDomainCombiner.
• setReadOnly – Allows the caller to set a Subject to be read-only.
• modifyPrincipals – Allows the caller to modify the Set of Principals associated
with a Subject.
• modifyPublicCredentials – Allows the caller to modify the Set of public credentials associated with a Subject.
• modifyPrivateCredentials – Allows the caller to modify the Set of private
credentials associated with a Subject.
• getPolicy – Allows the caller to retrieve the system-wide Subject-based access
control policy.
• setPolicy – Allows the caller to set the system-wide Subject-based access control
policy.
• refreshPolicy – Allows the caller to refresh the system-wide Subject-based
access control policy.
• refreshCredential – Allows code to invoke the refresh method on a credential which implements the Refreshable interface.
• destroyCredential – Allows code to invoke the destroy method on a credential object which implements the Destroyable interface.
• createLoginContext – Allows code to instantiate a LoginContext.
• getLoginConfiguration – Allows for the retrieval of the system-wide login
Configuration.
• setLoginConfiguration – Allows for the setting of the system-wide login Configuration.
• refreshLoginConfiguration – Allows for the refreshing of the system-wide
login Configuration.
10.2 Common User Questions
10.2.1
Published Questions and Answers
The JAAS FAQ, located at http://java.sun.com/security/jaas/faq.html,
contains answers to many commonly asked design and implementation questions. The
JAAS FAQ is updated frequently. As new user problems and concerns develop, they are
added to the FAQ.
10.2.2
Additional Developer Questions
The following are additional questions developers might have when using JAAS.
10.2.2.1 Determining Whether Security Policy Was Parsed Correctly and Is in Effect
How can I ensure that my security Policy was correctly parsed and is currently “in
effect”?
SUN MICROSYSTEMS, INC.
19 of 22
Troubleshooting
Run your application with JAAS debugging turned on by specifying the system property
java.security.auth.debug with the value policy. For example:
java -Djava.security.auth.debug=policy <yourApp>
where <yourApp> is the class name of your application.
The debug output will tell you each policy that was read in, as well as the permissions
granted in each policy.
10.2.2.2 Code Runs When Expecting a Security Exception
I did not grant a certain Permission in the JAAS policy, and the code still runs without
throwing a SecurityException. For example, I did not grant a FilePermission
in the JAAS policy, but my code can read the file without a SecurityException being
thrown! Why is that?
This probably means that you specified the FilePermission in the regular Java 2 policy. Recall that permissions specified in the regular Java 2 policy do not have any Principal information in the grant entry. This effectively means that the Principal information
defaults to a wildcard (*) value, and that these permissions are granted to any Subject.
If this is not the behavior you want, separate your code into different jar files. Grant subject-based permissions (in the JAAS policy) to the jar file that will run as a particular
subject. For a detailed example for doing this, please consult the sample application provided with the JAAS download. Directions for running the program, as well as information about its behavior, are documented in the JAAS API Developer’s Guide, located at
http://java.sun.com/security/jaas/doc/api.html.
10.2.2.3 Security Exception Occurs When Not Expected
I granted the necessary permission in the JAAS policy, but I still get a
SecurityException. What’s the problem?
Your code is probably structured something like this: Code A authenticates a Subject S
and then calls Subject.doAs(S, B), where S represents the authenticated Subject,
and B represents the action to be run as that Subject.
B performs security-sensitive tasks, and you have granted the necessary permissions to B
running as S in the JAAS policy, but you’re still getting a SecurityException.
The reason for this is that JAAS has a security measure that guarantees that the caller of
Subject.doAs (A in this case) can never increase its own permissions simply by calling Subject.doAs. Therefore, A must also have been granted all the permissions that
B requires. Since you did not grant the necessary permissions to A, you will get a SecurityException.
For a detailed example of properly structuring your code, and properly granting permissions, please consult the sample application provided with the JAAS download. Directions for running the program, as well as information about its behavior, are documented
in the JAAS API Developer’s Guide, located at http://java.sun.com/security/
jaas/doc/api.html.
SUN MICROSYSTEMS, INC.
20 of 22
Reference Information
10.2.2.4 Determining What Code Is Causing a Security Exception
How can I find out what code is causing a SecurityException to be thrown? In
other words, how can I find out what code has not been granted the appropriate Permissions?
Run your application with regular Java 2 security debugging turned on. Specify the System Property java.security.debug with the value access,failure (no spaces
are allowed). For example:
java -Djava.security.debug=access,failure <yourApp>
where <yourApp> is the class name of your application.
The debug output will display the code that failed based on its URL and code signers, as
well as the Permissions granted to that code.
10.3 Troubleshooting Utilities
JAAS provides some limited debugging assistance for developers. To enable the debugging feature, run applications with the System property:
java.security.auth.debug=<value>
where <value> is a comma-separated list of debug options (no spaces are allowed).
For example:
java -Djava.security.manager -Djava.security.debug=policy,auth <yourApp>
where <yourApp> is the class name of your application.
Table 4, “JAAS Debug Options,” lists the possible debug values.
TABLE 4.
JAAS Debug Options
Option
Meaning
all
Turn on all JAAS debugging
logincontext
LoginContext debugging
policy
Access control policy debugging
auth
Access control debugging
combiner
SubjectDomainCombiner debugging
11.0 Reference Information
11.1 Product Information
All of the relevant links for the JAAS framework and related documentation, including
white papers for JAAS, PAM, and the Java 2 security architecture, FAQs, slides, develSUN MICROSYSTEMS, INC.
21 of 22
Reference Information
oper’s guides, and download information can be reached from the main JAAS product
page, http://java.sun.com/products/jaas/.
The javadocs for the JAAS class libraries are available online from
http://java.sun.com/security/jaas/apidoc/index.html.
The javadocs for the JAAS sample LoginModules are available online from
http://java.sun.com/security/jaas/jaasmod/apidoc/index.html.
The JAAS API Developer’s Guide is available online from
http://java.sun.com/security/jaas/doc/api.html.
The LoginModule Developer’s Guide is available online from
http://java.sun.com/security/jaas/doc/module.html.
11.2 Frequently Asked Questions
Answers to common user questions can be found in the JAAS FAQ, located at
http://java.sun.com/security/jaas/faq.html.
11.3 Related Documentation
The following documents give background information on the security aspects of the
Java 2 Platform in general and JAAS in particular.
An online tutorial about security on the Java 2 platform is available at
http://java.sun.com/docs/books/tutorial/security1.2/index.html.
An overview of the Java Security Architecture for the Java 2 Platform is available at
http://java.sun.com/products/jdk/1.2/docs/guide/security/spec/
security-spec.doc.html.
The JAAS white paper, published in the Proceedings of the 15th Annual Computer
Security Applications Conference, Phoenix, AZ, December 1999, is available at
http://java.sun.com/security/jaas/doc/acsac.html.
11.4 Bug Reports, Questions, and Feedback
To submit JAAS bug reports or to submit requests for enhancements, access
http://java.sun.com/cgi-bin/bugreport.cgi.
SUN MICROSYSTEMS, INC.
22 of 22