Survey
* Your assessment is very important for improving the workof artificial intelligence, which forms the content of this project
* Your assessment is very important for improving the workof artificial intelligence, which forms the content of this project
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