Vintela Single Sign-on for Java. Deployment Guide JBoss Edition 3.2

Vintela Single Sign-on for Java Deployment Guide JBoss Edition 3.2

2007 Quest Software, Inc. ALL RIGHTS RESERVED. This guide contains proprietary information protected by copyright. The software described in this guide is furnished under a software license or nondisclosure agreement. This software may be used or copied only in accordance with the terms of the applicable agreement. No part of this guide may be reproduced or transmitted in any form or by any means, electronic or mechanical, including photocopying and recording for any purpose other than the purchaser's personal use without the written permission of Quest Software, Inc. If you have any questions regarding your potential use of this material, please contact: Quest Software World Headquarters LEGAL Dept 5 Polaris Way Aliso Viejo, CA 92656 USA www.quest.com email: legal@quest.com telephone: 949.754.8000 Please refer to our Web site for regional and international office information. TRADEMARKS Quest, Quest Software, the Quest Software logo, Aelita, Fastlane, Spotlight, and Vintela Single Sign-on for Java are trademarks and registered trademarks of Quest Software, Inc. Adobe Reader is a registered trademark of Adobe Systems Incorporated in the United States and/or other countries. Other trademarks and registered trademarks used in this guide are property of their respective owners. Vintela Single Sign-on for Java from Quest Software Deployment Guide Updated - April 2007 Software Version - 3.2

CONTENTS PREFACE........................................VII WHO SHOULD READ THIS GUIDE?................... VIII WHAT S IN THIS GUIDE?......................... VIII CONVENTIONS................................. IX CHAPTER 1: INTRODUCTION TO VSJ..................... 1 OVERVIEW................................... 2 ABOUT VSJ.................................. 2 ABOUT KERBEROS.............................. 3 ABOUT ACTIVE DIRECTORY......................... 5 ACTIVE DIRECTORY GROUPS..................... 6 ACTIVE DIRECTORY SITES....................... 9 PRINCIPALS, COMPUTER AND USER OBJECTS........... 9 VSJ AND ACTIVE DIRECTORY.....................10 SPNEGO AND INTERNET EXPLORER....................11 HOW DOES VSJ JBOSS EDITION WORK?................11 CHAPTER 2: PREPARING YOUR DEPLOYMENT ENVIRONMENT FOR VSJ........................................13 OVERVIEW...................................14 PRE-INSTALLATION..............................14 DOMAIN NAME SERVICE (DNS)...................14 TIME SYNCHRONIZATION SERVICE..................15 ACTIVE DIRECTORY...........................16 APPLICATION SERVER.........................16 CLIENT MACHINE............................16 DEPLOYMENT RISKS.............................18 SERVICE UNAVAILABILITY.......................18 TIME SYNCHRONIZATION.......................18 REPLICATION INTERRUPTIONS.....................19 RESOURCE SECURITY..........................19 iii

Vintela Single Sign-on for Java from Quest Software SETTING UP ACTIVE DIRECTORY ACCOUNTS FOR VSJ.........19 STEP 1: CREATE A USER ACCOUNT.................19 STEP 2: MAP A SERVICE PRINCIPAL NAME (SPN)........20 STEP 3: FINAL STEPS.........................21 SETTING UP ACTIVE DIRECTORY ACCOUNTS ON A VAS-ENABLED HOST......................................22 VINTELA AUTHENTICATION SERVICES (VAS)...........22 USING THE VAS HOST SERVICE PRINCIPAL NAME TO INSTALL VSJ............................23 CREATING A HTTP SERVICE PRINCIPAL USING VASTOOL....24 POST-INSTALLATION.............................25 SETTING UP INTERNET EXPLORER FOR SSO............25 CREATING KEYTAB FILES.......................27 CHAPTER 3: DEPLOYING VSJ JBOSS EDITION...............31 OVERVIEW...................................32 INSTALLING VSJ JBOSS EDITION.....................32 CONFIGURING THE VSJ EXAMPLES.....................33 DEPLOYING WEB COMPONENTS USING VSJ JBOSS EDITION.....35 SETTING UP LOGGING............................38 USING VSJ CREDENTIAL DELEGATION..................39 DELEGATING TO ANOTHER WEB RESOURCE USING SPNEGO.40 CROSS-DOMAIN ISSUES...........................41 CLIENT-SIDE CONFIGURATION....................42 BASIC FALLBACK............................42 CHAPTER 4: VSJ FEDERATION FOR JBOSS.................43 INTRODUCTION................................44 FEATURES...................................44 PREREQUISITES................................45 INSTALLATION.................................45 CONFIGURATION................................46 iv

Contents CHAPTER 5: USING THE JKTOOLS.......................49 OVERVIEW...................................50 THE JKTOOLS.................................50 JKINIT...................................50 JKLIST...................................50 JKTUTIL..................................51 EXAMPLES...................................51 CHAPTER 6: SECURITY ISSUES.........................53 OVERVIEW...................................54 SUMMARY OF BASIC RECOMMENDATIONS.................54 CLIENT ISSUES................................54 COOKIES.................................54 CACHING OF PASSWORDS FOR BASIC FALLBACK.........55 SPNEGO/WINDOWS INTEGRATED AUTHENTICATION..........55 LIFETIME OF AUTHENTICATION....................56 SESSION IDS.................................56 ACTIVE DIRECTORY PERMISSIONS.....................57 BASIC FALLBACK...............................59 KEYTABS AND PASSWORDS.........................60 AUTHORIZATION................................61 DO YOU NEED AUTHORIZATION?..................61 SECURING LDAP............................61 USING THE "PRINCIPLE OF LEAST PRIVILEGE"...........62 DENIAL OF SERVICE.............................62 BASIC FALLBACK............................62 SESSION STATE.............................62 AUDITING...................................63 NTLM AUTHENTICATION...........................63 WHAT IS NTLM?............................63 DIFFERENT VERSIONS OF NTLM...................64 NTLM AND INTERNET EXPLORER...................64 v

Vintela Single Sign-on for Java from Quest Software CHAPTER 7: MAINTENANCE AND TROUBLESHOOTING...........67 OVERVIEW...................................68 MAINTENANCE.................................68 LOGGING.................................68 NEW USERS / GROUPS........................68 ACCOUNT SETTINGS..........................68 NETWORK TOPOLOGY CHANGES...................69 TROUBLESHOOTING..............................69 GENERAL.................................69 ACTIVE DIRECTORY...........................71 BROWSERS................................71 AUTHENTICATION............................73 KEYTABS.................................76 NETWORK CONNECTIONS.......................76 CREDENTIAL DELEGATION.......................77 DEBUGGING...............................77 APPENDIX A: VSJ CONFIGURATION PARAMETERS.............79 GLOSSARY......................................87 INDEX.........................................91 vi

Preface As the use of distributed systems increases, users need to access resources that are remotely located. Traditionally users have had to sign-on to multiple systems, many requiring different usernames, passwords and authentication techniques. With single sign-on (SSO), users need only authenticate once and the authenticated identity is securely carried across the network to access resources on behalf of the user. The Java Platform, Enterprise Edition (Java EE ) is an excellent platform for developing Internet, intranet and extranet applications. It provides a standardized architecture that makes reuse possible, and provides tight integration with databases and legacy applications through the JDBC and JCA interfaces. Many enterprises have deployed, or are in the process of deploying Java EE applications. In addition, many enterprises are moving to support a standardized authentication infrastructure. In particular, Microsoft 's Active Directory provides an environment based on Kerberos and LDAP which provide Identity Management services including SSO, a centralized store for identity information. It makes a lot of sense to reuse this infrastructure where possible. Unfortunately, tight integration with Kerberos, and in particular the infrastructure provided by Microsoft s Active Directory which is already deployed or being deployed in many organizations, is simply not available for Java EE. Vintela Single Sign-on for Java from Quest Software fills this gap, providing SSO and access management for Java EE applications using Active Directory as their identity store. It provides an enterprise-wide method of identification and authorization that can be administered in a consistent and transparent manner and allows users to access information systems to which they are authorized.

Vintela Single Sign-on for Java from Quest Software Who Should Read This Guide? The VSJ (JBoss Edition) Deployment Guide is intended for developers of VSJ solutions for enterprise SSO applications. You should have a good knowledge of Java programming, and a sound understanding of how Active Directory works in your environment. What s in This Guide? This guide describes how to deploy VSJ and includes a number of examples designed to accelerate the implementation of your VSJ solution. The VSJ (JBoss Edition) Deployment Guide includes: Chapter 1: Introduction to VSJ This chapter introduces VSJ as well as covering underlying technologies, such as Kerberos, Active Directory and SPNEGO, and includes an outline of VSJ s operations from the point of initialization through to exit. Chapter 2: Preparing Your Deployment Environment for VSJ This chapter discusses the environment needed for a VSJ deployment, including the DNS implementation, time synchronization service issues, Active Directory installation, and your application server and client machine software requirements. Chapter 3: Deploying VSJ JBoss Edition This chapter describes how to install VSJ JBoss Edition and then build SSO solutions using VSJ-protected Servlets and JSPs. Chapter 4: VSJ Federation for JBoss This chapter describes VSJ JBoss Federation which provides single sign-on for web applications in a Microsoft ADFS (Active Directory Federation Services) environment. Chapter 5: Using the JKTools This chapter describes how to use the jkinit, jklist and jktutil tools which are included with VSJ. Chapter 6: Security Issues This chapter outlines the mechanisms in VSJ used to achieve secure operation, and outlines some areas that may need attention. viii

Preface Chapter 7: Maintenance and Troubleshooting This chapter discusses the common maintenance issues relating to a VSJ deployment and provides solutions to some common problems which may be experienced when configuring and deploying applications using VSJ. Glossary The Glossary provides definitions of the terminology used in this guide. Conventions Conventions used in this guide are shown below. Convention Code Code italic SansSerif SansSerif italics Italic Use Highlights commands and coding Highlights code variables Highlights file names and paths Highlights file name and path variables Highlights publication titles and emphasises important or new terms ix

Vintela Single Sign-on for Java from Quest Software x

1 Introduction to VSJ Overview About VSJ About Kerberos About Active Directory SPNEGO and Internet Explorer How Does VSJ JBoss Edition Work?

Vintela Single Sign-on for Java from Quest Software Overview This chapter introduces VSJ as well as covering underlying technologies, such as Kerberos, Active Directory and SPNEGO, and includes an outline of VSJ s operations from the point of initialization through to exit. About VSJ VSJ provides a mechanism for integrating Java EE applications into an enterprise SSO infrastructure based on Active Directory. It supports authentication and authorization with Active Directory and in particular supports the SPNEGO protocol with Internet Explorer and Firefox/Mozilla. This allows Java EE Servlets and JSPs to authenticate users using Kerberos, and to use delegated credentials to access other Kerberized services within an enterprise domain. VSJ utilizes a number of other Active Directory features such as Active Directory groups and Active Directory sites. VSJ supports the authorization of users using Active Directory groups. By specifying which Active Directory groups are allowed to access an application, you can control access by managing group membership. Active Directory sites represent the physical topology of an Active Directory-based network infrastructure, and allow for replication, redundancy and load balancing across the network. VSJ uses Active Directory sites to support replication and failover. By using the VSJ solution you will be able to provide: End-to-end authentication between users and backend services Authorization of users by using Active Directory groups Integration of Java EE applications in an Active Directory/Kerberos-based SSO environment A cross-platform solution which supports most operating systems and Java application servers 2

Introduction to VSJ Figure 1 shows a conceptual view of a typical VSJ deployment. Figure 1: Conceptual View of a Typical VSJ Deployment About Kerberos Kerberos is a network authentication protocol developed at the Massachusetts Institute of Technology (MIT). It is designed to provide strong authentication for client/server applications across insecure network connections by using secret-key cryptography. It allows entities communicating over networks to prove their identity to each other while preventing eavesdropping or replay attacks. It also provides for data stream integrity (detection of modification) and secrecy (preventing unauthorized reading) using cryptographic ciphers such as DES. Kerberos works by providing principals (users or services) with tickets that they can use to identify themselves, and secret cryptographic keys for secure communication with other principals. A ticket is a sequence of a few hundred bytes. The ticket can then be used to secure virtually any other network 3

Vintela Single Sign-on for Java from Quest Software protocol, thereby allowing the processes implementing that protocol to be sure about the identity of the principals involved. Kerberos provides for mutual authentication and secure communication between principals on an open network by manufacturing secret keys for any requester and providing a mechanism for these secret keys to be safely propagated through the network. Kerberos does not, strictly speaking, provide for authorization or accounting, although applications may use their secret keys to perform those functions securely. There are several versions and distributions of Kerberos. Most of them are based on the MIT distributions. Some of the distributions are freely available, some are standalone commercial products, and others are part of larger free or proprietary systems. MIT Kerberos versions 4 and 5 are freely available. Versions 4 and 5 are based on completely different protocols, however version 5 contains some compatibility code. Figure 2: Kerberos Protocol Figure 2 shows how the Kerberos protocol works. A principal authenticates itself in Kerberos by using a principal name of the form principal-name@realm and a password. This is typically used to send an encrypted message to the 4

Introduction to VSJ Authentication Service (AS), which can then authenticate the principal and send back a session key and Ticket Granting Ticket (TGT). The TGT is like a certificate of identity which allows the principal to gain later access to one or more services. Once the user has supplied their password and obtained the TGT from the AS, authentication to any other service can happen automatically without the user having to resupply their password. For this reason, Kerberos is sometimes called a Single Sign-On (SSO) service. A ticket is a credential that enables a principal to gain access to a service. A principal obtains tickets from the Ticket Granting Service (TGS) using the TGT obtained from the AS as described above. The ticket is used to create an authenticator, which is then sent to the service being requested to authenticate the user. The authenticator is used to establish a session key for secure communication. Optionally, the user can also request to authenticate the server. If this happens, the server uses information in the user's authenticator to send back a server authenticator, which the user can use to verify the server's authenticity. The Kerberos protocol has been widely analyzed and is supported by many vendors including Sun, Microsoft and Oracle to name a few. It forms the basis of the authentication system used by Active Directory in Windows operating systems. About Active Directory The Active Directory service is a core component of the Microsoft Windows operating system. It provides a directory service supporting the Lightweight Directory Access Protocol (LDAP), and a Kerberos KDC to authenticate users. It allows organizations to share and manage information about network resources and users and provides an SSO environment that integrates with the standard Windows desktop login. In addition, it acts as a single point of management for Windows-based user accounts, clients, servers and applications. The directory is arranged hierarchically, allowing the division of enterprise resources into different domains. Each resource (i.e., user, application), is represented as an object with a number of attributes (for example, the organizational group to which the resource belongs). The directory may be browsed hierarchically for resources, or each resource can be individually addressed by providing its Distinguished Name. The Distinguished Name is simply a group of attributes that uniquely identify an object within the Active Directory hierarchy (for example, CN=John Doe, DC=example, DC=com ). The directory also provides fine-grained security mechanisms to allow administrators to determine exactly what information may be accessed. Users 5

Vintela Single Sign-on for Java from Quest Software can be restricted to specific objects, or even specific attributes within the directory. The main benefits of using Active Directory are that it simplifies the management of user accounts, and provides an SSO infrastructure to users. Its support for standard protocols such as LDAP and Kerberos means that it can be used as, or with, a cross-platform solution. The Kerberos support in Active Directory has been tested to ensure interoperability with the MIT Kerberos implementation used by many UNIX vendors. However, it is worth noting some differences between the Microsoft and MIT implementations: Support for Privilege Attribute Certificates (PACs) Microsoft's Kerberos implementation uses the AuthorizationData field of the Kerberos ticket to pass Privilege Attribute Certificates (PACs) to Kerberized applications. Applications that support Microsoft's PAC format can use this information to provide fine-grained access control to services. Integration with LDAP Active Directory's Kerberos features are tightly integrated with its LDAP server. This means that user information, such as groups, can be retrieved using standard tools and APIs. Windows Native Credential Cache Unlike the MIT implementation, the Windows Kerberos implementation uses an in-memory credential cache to store Kerberos tickets and TGTs (the MIT implementation uses a disk file). The implementation is stored in non-paged memory so it is never written to disk. Microsoft provides routines to obtain credentials from this cache through their Local Security Authority API (LSA API). Smartcard / PKI Support Microsoft supports a version of the PKINIT protocol which allows the initial authentication to the directory to be performed using a private key or smartcard. Active Directory Groups In large organizations, managing the authorization permissions of hundreds or even thousands of users creates a significant problem. One way that Active Directory addresses this issue is through the use of groups. These groups provide a way to classify users according to their roles or activities, and can be used as the basis for authorization permissions. 6

Introduction to VSJ Group Types Active Directory defines two types of groups: security groups and distribution groups. Distribution groups are mainly used for activities such as sending bulk email, and do not allow permissions and audit settings to be associated with them. Security groups on the other hand are primarily designed for authorization, so are most interesting for VSJ. Microsoft Windows does not use distribution groups internally, although they are available for use by other directory-enabled applications. Group Scopes Each group has a scope which describes both its visibility to other users and applications throughout the enterprise, and the types of principals that can be included in the group. The three group scopes are listed below: Domain Local visible only within a domain, and to sub-domains. Domain local groups can include any other type of group, but cannot be included in any of the other groups. Commonly, Domain local groups are used to define the groups and users allowed to access a given local resource. Global visible throughout the enterprise, but can only include other users and groups within the same domain (or a parent domain). Global groups should be used to divide users within a domain into categories according to their roles or job functions. Universal visible throughout the entire enterprise. Universal groups may include both other Universal groups, and global groups from any domain in the enterprise. For reasons described below, Universal groups are expensive to use, so try to limit the number of these groups. You should use a Universal group wherever it is necessary to create a group that spans one or more domains. If you are using Active Directory in mixed mode (that is, with both Active Directory and Windows NT domains) the rules for scoping are more restrictive, and you cannot use Universal groups. See your Active Directory documentation for more details. Active Directory allows nested groups (groups that contain other groups), which can be nested to arbitrary levels. This is convenient, as it provides a way to hierarchically manage users, for example you can have a group for each type of manager in a department, and then create a group called Managers that includes all of these sub-groups. 7

Vintela Single Sign-on for Java from Quest Software Groups and the Logon Process When a Microsoft Windows user logs on to an Active Directory domain, Active Directory builds a token called a Privilege Attribute Certificate (PAC). The PAC contains the list of all the groups the user is a member of, and that are visible in the login domain. This list is the "transitive closure", meaning it includes any groups which the user is a member of due to nesting of other groups. For example, supposing we have the following global groups which contain the users "Alice" and "Bob": Group1 : contains Alice, Bob Group2 : contains Group1 Group3 : contains Group2 Then the PAC for Alice will contain Group1, Group2 and Group3. Computing this group membership can take some time and Active Directory may have to query several LDAP servers to determine membership. In addition, Universal groups require a full search of the global catalog, which stores information about every Active Directory object. For this reason, the number of Universal groups should be limited to ensure that logon times do not become too long. The PAC exists for the lifetime of the initial TGT obtained at logon time (typically 10 hours). For this reason, if a user is added to a new group, the user must log off and then log back on for this group to be used. Groups and VSJ When a user accesses an application protected with VSJ, Internet Explorer will contact Active Directory to obtain a service ticket for the server which it needs to contact, or retrieve it from the cache if available. This service ticket will contain a PAC containing all the Universal and Global groups from the user's existing PAC, plus any Domain Local groups defined in the servers domain. VSJ will then use the groups defined in the PAC to authorize access to a particular resource. Because the group membership is securely authenticated in the PAC, VSJ can trust this information. Using the PAC also saves time associated with the LDAP lookups needed to recursively resolve group membership, resulting in a more scalable solution. 8

Introduction to VSJ Active Directory Sites Sites represent the physical topology of your Active Directory infrastructure based on subnets of TCP/IP addresses, and allow for replication, redundancy and load balancing across your Active Directory deployment. By defining sites in Active Directory, you effectively tell Active Directory what your underlying physical network looks like. This allows domain controllers to utilize the underlying network in the most efficient manner possible and allows Active Directory to conserve bandwidth that is required for other applications within your organization. However, sites are not related to the structure of the domain, nor must they maintain the same namespace a site may span multiple domains and, conversely, a domain may span multiple sites. While no formal relationship exists between a site and a domain, a site may be given the same boundaries as a domain. To ensure rapid and reliable network communication, Active Directory offers methods of regulating intersubnet, or intersite, traffic. The Active Directory physical structure governs when and how replication takes place. As users log on to the network, they are able to reach the closest domain controller site through the previous assignment of subnet information. The system administrator uses the Active Directory Sites and Services snap-in to manage the topology of replication services. VSJ supports replication and failover using Active Directory sites Principals, Computer and User Objects Active Directory uses a number of different names to refer to objects that are used by VSJ. These are discussed below. User Principal Name (UPN) The fully qualified name used as the Kerberos client principal name. It consists of an RFC822/Email style name and domain separated by an '@'. The UPN must be unique throughout the Active Directory forest. The UPN is the name that will appear in the Kerberos Ticket Granting Ticket (TGT) for a client returned by Active Directory. 9

Vintela Single Sign-on for Java from Quest Software Service Principal Name (SPN) The fully qualified name of a Kerberos service principal. The SPN is of the form <service>/<host>@domain, for example: HTTP/foo.example.com@EXAMPLE.COM The SPN is used when requesting a Kerberos ticket for a particular service. You will typically need to map an SPN to an Active Directory user or computer object using either the setspn or ktpass utilties with Microsoft Windows. Computer/User Objects SPN/UPNs may be mapped to two different types of object in Active Directory. Computer objects refer to computers which have been joined to a given Active Directory domain (for example, a Microsoft Windows machine joined using the Network Identification Wizard, or a Unix machine joined using VAS). When the computer object is created a corresponding HOST/<machine name>@<domain> SPN will be mapped to that computer object. It is also possible to map additional SPNs to the computer object. An Active Directory User object may refer to an actual physical person, or a Service Account which is an object created for the purposes of running a particular service. In the latter case you would map the SPN to the service account using the setspn or ktpass utilities with Microsoft Windows. Use of Principal Names in VSJ When running VSJ on Microsoft Windows it is only possible to configure VSJ to use the HTTP SPN mapped to a Service Account User Object. This is because it is not possible for VSJ to access the key material for the Computer account stored in the LSA database. For more details on setting up VSJ to use a Service Account, see Setting Up Active Directory Accounts for VSJ). However, when VSJ is used with Vintela Authentication Services (VAS), either the HOST/ or HTTP/ mechanisms can be used (see Setting Up Active Directory Accounts on a VAS-Enabled Host for more details). VSJ and Active Directory VSJ has been specifically designed to work optimally with Microsoft's Active Directory. It will use the default configuration to discover the services, hosts and port numbers necessary to integrate with Active Directory. To finetune your deployment you can configure VSJ to use Active Directory configuration such as sites and services, KDC servers, etc. 10

SPNEGO and Internet Explorer Introduction to VSJ In addition to support for Kerberos through its Active Directory service, Microsoft has also provided extensions to Internet Explorer that allow it to participate in a Kerberos-based SSO environment. When a Web server receives a request from an Internet Explorer browser, it can request that the browser use the SPNEGO protocol to authenticate itself. This protocol performs a Kerberos authentication which is tunneled over HTTP, and allows Internet Explorer to pass a delegated credential so that a Web application can log in to subsequent Kerberized services on the user's behalf. When an HTTP server wishes to perform SPNEGO, it returns a "401 Unauthorized" response to the HTTP request with the "WWW-Authorization: Negotiate" header. Internet Explorer then contacts the Ticket Granting Service (TGS) to obtain a service ticket. It chooses a special Service Principal Name for the ticket request, which is: HTTP/webserver@REALM The returned ticket is then used to construct an SPNEGO token which is encoded and sent back to the server in the HTTP headers. The token is unwrapped and the ticket is authenticated. If mutual authentication is required, then the Web server can return an additional SPNEGO token for the client to verify. Once authenticated, the page corresponding to the requested URL is returned. SPNEGO provides a useful mechanism for extending an SSO environment to Web applications. It is already supported in Microsoft IIS for authentication to ASP or Web pages. In addition, the ability to delegate credentials means that a Web application can log in to further services transparently on the user's behalf, providing full end-to-end authentication. Lastly, SPNEGO and HTTP can be used for authentication with Microsoft.NET SOAP clients, providing SSO for Web services. How Does VSJ JBoss Edition Work? This section provides an outline of VSJ JBoss Edition s operations, from the point of initialization through to exit. On startup The VSJ-enabled Tomcat Valve examines the vsj.properties file to determine the default realm, service principal name (SPN), password or keytab, etc. and then calls initauthenticator, which gets a server Ticket-Granting Ticket (TGT). 11

Vintela Single Sign-on for Java from Quest Software For each request to a protected area, the VSJ-enabled Valve calls authenticate(request, Response, LoginConfig) VSJ performs the appropriate authentication for the mechanism specified in the request (specified in the 'Authorization' header of the request): Basic fallback (if configured): Mechanism name is "Basic", and mechanism token is a base64-encoded username and password. Converts username and password to a Kerberos principal and Kerberos password, and requests a TGT from the KDC. Requests a service ticket from the KDC.Stores credentials in session state for future authentication requests. NTLM (if configured): Mechanism name is "NTLM" or "NEGOTIATE", and mechanism token is an NTLM token. An NTLM handshake occurs, where messages are exchanged between the client and server including negotiate, challenge and authenticate packets. Once authentication occurs, a credential is obtained and stored in the session state for future authentication requests. SPNEGO Mechanism name is "Negotiate", and mechanism token is an SPNEGO token. SPNEGO handshake occurs, whereby the SPNEGO token in the request is processed, and SPNEGO tokens may be returned to the browser in the "WWW-Authenticate' field of the response. Eventually, authentication succeeds, and credentials are obtained. The session state is updated with the obtained credentials and other user information. The Valve passes the Authenticated User details to a JBoss LoginModule that will create a JAAS Subject during the login process using the information provided. JBoss Security Mechanism (JBossSX) will allow/deny permission based on information packed inside the Subject. 12

2 Preparing Your Deployment Environment for VSJ Overview Pre-Installation Deployment Risks Setting Up Active Directory Accounts for VSJ Setting Up Active Directory Accounts on a VAS-Enabled Host Post-Installation

Vintela Single Sign-on for Java from Quest Software Overview This chapter discusses the environment needed for a VSJ deployment, including the DNS implementation, time synchronization service issues, Active Directory installation, and your application server and client machine software requirements. If you are not already familiar with Active Directory and other concepts related to VSJ, refer to Introduction to VSJ. Pre-Installation Domain Name Service (DNS) VSJ requires a DNS implementation to discover the location of: KDCs for a given realm Domain controllers and global catalogs for a given domain (and optionally for a given site) The DNS implementation must support SRV resource records as follows: For locating the domain controller(s) for a given domain: _ldap._tcp.domain where domain is the given domain. For example: _ldap._tcp.testsso.example.com would represent the SRV query for finding domain controllers representing the domain TESTSSO.EXAMPLE.COM. For locating the domain controller(s) for a given domain in a given site: _ldap._tcp.site._sites.domain where site is the given site and domain is the given domain. For example: _ldap._tcp.brisbane._sites.testsso.example.com would represent the SRV query for finding domain controllers representing the domain TESTSSO.EXAMPLE.COM for the site Brisbane. 14

Preparing Your Deployment Environment for VSJ For locating the global catalog(s) for a given domain: _ldap._tcp.gc._msdcs.domain where domain is the given domain. For example: _ldap._tcp.gc._msdcs.testsso.example.com would represent the SRV query for finding global catalogs representing the domain TESTSSO.EXAMPLE.COM. For locating the global catalog(s) for a given domain in a given site: _ldap._tcp.site._sites.gc._msdcs.domain where site is the given site and domain is the given domain. For example: _ldap._tcp.brisbane._sites.gc._msdcs.testsso.example.com would represent the SRV query for finding global catalogs representing the domain TESTSSO.EXAMPLE.COM for the site Brisbane. DNS services may be provided by using a Windows DNS server, or by using a Unix BIND DNS server. All DNS servers must be physically and logically secure. For information on configuring DNS for Microsoft Windows, see: The Microsoft Windows Server 2003 Deployment Kit (http://www.microsoft.com/resources/documentation/windowsserv/20 03/all/deployguide/en-us/Default.asp) Using BIND DNS Servers with Windows 2000 Detailed Instructions (http://research.microsoft.com/programs/up_content/bind.doc) For information on configuring DNS for Unix, see the BIND 9 Administrator Reference Manual (http://www.nominum.com/content/documents/bind9arm.pdf). Time Synchronization Service The Kerberos protocol requires synchronization of internal clocks within Kerberos domains, to ensure that ticket lifetimes may be calculated and compared correctly. A time service may be configured to provide the necessary synchronization. Time services may be provided by the Unix Network Time Protocol (NTP) service, or the compatible Simple Network Time Protocol (SNTP) service available with Microsoft Windows. 15

Vintela Single Sign-on for Java from Quest Software For information on configuring time services for Microsoft Windows, see: How to Configure an Authoritative Time Server in Windows XP (http://support.microsoft.com/?kbid=314054) How to Configure an Authoritative Time Server in Windows 2000 (http://support.microsoft.com/default.aspx?scid=216734) For information on configuring time services for Unix, see NTP: The Network Time Protocol (http://www.ntp.org/). Active Directory A Microsoft Windows 2000 Server or Windows Server 2003 Active Directory is required. The default installation is sufficient. 1. Install Microsoft Windows 2000 Server or Windows Server 2003. 2. Add the Active Directory role to the server. 3. You will be asked if you also want to install the DNS Role. If you do, click OK. You will need an Administrator account and password for the Active Directory domain. Application Server See the release notes (HTML) for a comprehensive list of servers supported by VSJ. Client Machine Operating System To support Windows Integrated Authentication, the client must be part of the Active Directory domain and must have one of the following operating systems installed: Windows 2000 Professional Windows 2000 Server Windows 2000 Advanced Server 16

Preparing Your Deployment Environment for VSJ Windows XP Professional Windows Server 2003 Windows Vista These are the only operating systems that incorporate Active Directory. If Microsoft Windows 2000 is installed on the client, Internet Explorer 5.5 or higher is also needed. To support NTLM authentication, one of the following operating systems must be installed on the client: Windows 95 Windows 98 Windows Millennium Edition (ME) Windows NT Windows XP Home These operating systems do not incorporate Active Directory, but do support NTLM authentication. For more information on NTLM, see Security Issues. Basic fallback is supported on most platforms and browsers, such as Mozilla and Konqueror. Browser To support Windows Integrated Authentication, you will need one of the following browsers: Internet Explorer 5.5 or higher Mozilla Firefox 17

Vintela Single Sign-on for Java from Quest Software When using a browser that is not configured for Windows Integrated Authentication, VSJ provides both an NTLM mechanism that allows NTLM SSO, and a fallback mechanism that allows a user to log in with their Kerberos password using standard HTTP basic authentication. However, the basic feature is disabled by default for security reasons. For more details on the consequences of enabling basic fallback see Security Issues. Deployment Risks This section discusses some of the deployment risks associated with the implementation of a VSJ-based solution. These risks are not inherent to VSJ, but may impact on VSJ s service availability or result in false positive/negative authentication. Service Unavailability If a host (for example, the domain controller indicated by a DNS SRV query) becomes unavailable, then VSJ processing may be suspended until a timeout expires. Note that VSJ maintains an internal database of unavailable hosts, and subsequent requests will ignore (for a time) any hosts that are known to be unavailable. If no hosts are available for a given service, VSJ will indicate an error. Any subsequent VSJ operations that must communicate with the host will timeout until such time as the host becomes available. If a service (such as DNS) becomes unavailable, VSJ processing may be suspended until a timeout expires. After this, VSJ will indicate an error. Any subsequent VSJ operations that rely on the service will timeout until such time as the service becomes available. Time Synchronization If the internal clocks of two machines or services are sufficiently out of skew, then a Kerberos ticket which is valid on one machine may not be valid on the other machine. Thus, unsynchronized time services may lead to denial of service for otherwise valid Kerberos tickets. 18

Preparing Your Deployment Environment for VSJ Replication Interruptions VSJ supports replicated domain controllers and global catalogs, and assumes that information is replicated across the network topology in a timely and consistent manner. Failure to replicate security information (such as group membership, SIDs, etc.) accurately may result in authentication or authorization failures. Resource Security VSJ relies on sensitive data (such as Kerberos keytabs, passwords, and Active Directory account information). Such data must be physically and logically secure. Typically, only the Active Directory administrator should have access to Active Directory configuration, and a keytab should be readable only by the principal represented by that keytab. Setting Up Active Directory Accounts for VSJ The following sections describe the procedures for setting up Active Directory for VSJ. 1. Create a User Account 2. Map a Service Principal Name (SPN) 3. Final Steps If you are installing VSJ on Windows, before you begin, make sure that IIS is not being used on the same machine. The steps below will add a service principal name (SPN), which will clash with IIS's, causing IIS to no longer be able to decrypt Kerberos tickets. This will cause IIS's Windows Integrated Authentication to fail. Step 1: Create a User Account To set up user authentication for a service you must register the service as a user in Active Directory on the Domain Controller. This can be done using the following steps: 1. On the Domain Controller with Active Directory installed, click the Start menu, point to Programs, point to Administrative Tools, and then click Active Directory Users and Computers. 19

Vintela Single Sign-on for Java from Quest Software 2. Click the Users folder to display a list of users, on the Action menu, point to New, and then click User. Enter a name and logon name for the new service, and click Next. The username should consist of standard alphanumeric characters and no whitespace, as it needs to be entered in a command prompt later. On the next screen, enter a password for the service. Ensure that User must change password at next logon is not selected, and Password Never Expires is selected. Click Next, and then Finish. 3. Right-click the user you just entered in the User folder list, and then click Properties. A dialog box will display. 4. Select the Account tab. Select the Account is trusted for delegation check box if you wish to allow a service to use delegated credentials to access other services on the users' behalf. This is significant when your service depends on data from other secure services for which you don't want users to have to enter credentials manually. 5. Select the Password never expires check box. This prevents the service account from ever expiring, which would cause Kerberos errors. 6. Click OK. Step 2: Map a Service Principal Name (SPN) For Internet Explorer to be able to authenticate to VSJ, it needs to know the user account created in Create a User Account above. It does this by looking up a Service Principal Name (SPN) of the form HTTP/host.domain@REALM. The following describes how to create a mapping between a user account and an SPN: 1. Obtain the ktpass utility. This is available from the Windows 2000 resource kit. For more information on this tool, go to: http://www.microsoft.com/windows2000/techinfo/planning/security/kerb steps.asp ktpass is included on the Windows Server 2003 installation CD under /Support/Tools/. 2. Launch a command prompt and run ktpass with the following arguments: ktpass -princ HTTP/host.domain@REALM -mapuser user 20

Preparing Your Deployment Environment for VSJ Where: host.domain is the fully-qualified domain name of the server where VSJ will be installed. (for example, server.example.com) REALM is the Active Directory realm in which the server is located (for example, EXAMPLE.COM). Note that REALM needs to be entered in uppercase characters. user is the logon name of the user account you created above. If you want to use ktpass under Microsoft Windows 2003, the user must be the user account's full-name and must be enclosed by quotes (" "). Ensure that the principal name (SPN) you are entering at this step does not already exist in Active Directory, otherwise the installation will not work. The most common reason for this is if IIS has been installed on the host. Removal of IIS does not remove the principal name. This has to be done manually using the setspn.exe utility. If you wish to use a file keytab, refer to Creating Keytab Files. Step 3: Final Steps To prevent Kerberos integrity-check failures later on, ensure that you perform the following steps: 1. On the Domain Controller with Active Directory installed, click the Start menu, point to Programs, point to Administrative Tools, and then click Active Directory Users and Computers. 2. Right-click on the user account that you created previously, and click Reset Password... A login dialog box will display. 3. Enter and confirm the same password that you entered previously. Ensure that User must change password at next logon is not selected. 4. Click OK to finish. 21

Vintela Single Sign-on for Java from Quest Software Setting Up Active Directory Accounts on a VAS-Enabled Host VSJ supports integration with Vintela Authentication Services (VAS) to allow you to simplify installation on VAS-enabled Unix hosts. The following sections describe how to perform this setup. Vintela Authentication Services (VAS) Vintela Authentication Services (VAS) allows Unix and Linux users to be authenticated using Active Directory. It provides integration with the Unix Pluggable Authentication Modules (PAM) and Name Service Switch (NSS) systems. A system administrator will enable VAS on a Unix host by joining it to the Active Directory domain using the vastool utility. This creates a computer account object in Active Directory along with a HOST principal and keytab that can be used to authenticate service tickets that are presented to Kerberos/VAS-enabled applications. VAS Configuration The VAS Configuration file is usually installed in /etc/opt/vas/vas.conf. The configuration is in the form of an MIT krb5.conf file, for example: [libdefaults] default_realm = EXAMPLE.COM dns_lookup_kdc = true ticket_lifetime = 36000 default_keytab_name = /etc/opt/vas/host.keytab default_etypes = arcfour-hmac-md5 default_etypes_des = des-cbc-crc default_tkt_enctypes = arcfour-hmac-md5 des-cbc-crc default_tgs_enctypes = arcfour-hmac-md5 des-cbc-crc [domain.realm] j2ee.example.com = EXAMPLE.COM The configuration file defines information such as the default realm, and the location of the server keytab. 22

Preparing Your Deployment Environment for VSJ VAS Keytabs VAS keytab files are created in the /etc/opt/vas directory. Each keytab file is named according to the service that uses it. For example, the host principal keys are stored in the /etc/opt/vas/vintela/host.keytab file. VAS keytab files are stored using the standard MIT-style and may be used by third party applications including VSJ. vastool vastool is a command line program that allows you to configure various components of VAS, access information stored in Active Directory; and to perform a variety of tasks such as the creation of user accounts and keytabs. vastool is located at /opt/vas/bin/vastool. It has been designed to be script-friendly and to allow administrators to easily manage users, groups, and other information stored in Active Directory from Unix/Linux workstations. In order to run vastool, you must specify the options for vastool, a command to run, and the options for that specific command. While vastool supports a wide variety of commands, the following will be of most use when installing VSJ with VAS: create create a user, group, or computer object in Active Directory delete delete users, groups, computer objects, or NIS Map objects in Active Directory service manage service accounts in Active Directory Using the VAS HOST Service Principal Name to Install VSJ One of the simplest ways to configure VSJ to run on a VAS enabled host is to set up your configuration so that the Application Server can authenticate using the HOST principal installed when you join a VAS enabled machine to the Active Directory domain. To do this, you will need to perform the following steps: 1. Run the application server with sufficient permissions to access the host keytab /etc/opt/vas/host.keytab (usually root). 2. Configure the realm used by VSJ to be the same as the realm/domain to which the VAS enabled host has been joined. This can be determined by running the command: /opt/vas/bin/vastool info domain 23

Vintela Single Sign-on for Java from Quest Software 3. Configure VSJ to use the host keytab (located in /etc/opt/vas/host.keytab). 4. If you are using Active Directory sites you should configure VSJ to use the correct site for this server. You can discover this by using the command: /opt/vas/bin/vastool info site 5. Configure VSJ to use the HOST principal. This should be set to: HOST/fully.qualified.host.name Creating a HTTP Service Principal Using vastool It is also possible to use vastool to add a service account for VSJ rather than using the HOST principal. The major benefit of this approach is allows you to run the application server as an unprivileged user. To do this you will require VAS 2.6.24 or later. 1. To create the service, run the following command: $ vastool -u <Administrative User> service create HTTP/fully.qualified.host.name Where <Administrative User> is a domain user with sufficient permissions to create accounts. This will generate output similar to the following: Successfully created service HTTP/fully.qualified.host.name@EXAMPLE.COM Update the permissions on the service keytab for the application using the service. and generate a keytab /etc/opt/vas/http.keytab. 2. Modify the permissions on /etc/opt/vas/http.keytab so it is readable by the process running the application server. For example: $ chown appserverowner /etc/opt/vas/http.keytab 3. Configure the realm used by VSJ to be the same as the realm/domain to which the VAS-enabled host has been joined. This can be determined by running the command: $ /opt/vas/bin/vastool info domain 4. If you are using Active Directory sites you should configure VSJ to use the correct site for this server. You can discover this by using the command: $ /opt/vas/bin/vastool info site 24

Preparing Your Deployment Environment for VSJ 5. Configure VSJ to use the HTTP principal above (HTTP/fully.qualified.host.name). See Table 4, Standard VSJ Configuration Parameters, on page 40. Post-Installation Setting Up Internet Explorer for SSO This section describes how to set up Internet Explorer for SSO. This includes: Windows Integrated Authentication NTLM authentication Troubleshooting your Internet Explorer configuration Windows Integrated Authentication To take full advantage of VSJ, you must enable Windows Integrated Authentication. To use Windows Integrated Authentication, clients must be running Internet Explorer 5.5 or higher on Windows 2000/2003/XP. You should also ensure that the High Encryption Pack (see http://www.microsoft.com/windows/ ie/downloads/recommended/128bit/default.mspx) is installed. You can confirm that the High Encryption Pack is installed by selecting About Internet Explorer from the Help menu in Internet Explorer. If it is installed, Cipher Strength: 128-bit will be shown on the About Internet Explorer dialog box. You will probably need to ensure that the Java EE server on which you installed VSJ is in the Intranet Zone. See Troubleshooting Your Internet Explorer Configuration on page 37 for more information. Windows Integrated Authentication is enabled by default on Internet Explorer 5.5. If you are using Internet Explorer 6.0 or higher you will also need to do the following: 1. In Internet Explorer, on the Tools menu, click Internet Options. 2. Click the Advanced tab. 3. Scroll down to the Security section, and select the Enable Integrated Windows Authentication (requires restart) setting. 25

Vintela Single Sign-on for Java from Quest Software 4. Click OK. 5. Restart Internet Explorer. NTLM Authentication Windows Integrated Authentication provides a greater degree of security than NTLM authentication, so we recommend that users should attempt to use Windows Integrated Authentication unless it is unsupported by their client operating system or browser. To use NTLM for SSO, you will need a version of Windows that supports NTLM challenge/response (see Operating System). To set up Internet Explorer for NTLM authentication: 1. Configure the intranet for authentication: a. In Internet Explorer, on the Tools menu, click Internet Options. b. Click the Security tab. c. Click the Local intranet icon and then click Custom Level... d. Scroll down the Security Settings list to the User Authentication section, and select the Automatic logon only in Intranet zone option. This will configure the intranet for SSO. e. Click OK. 2. If you are using Internet Explorer 6.0 or higher, you will also need to perform the following steps: a. In Internet Explorer, on the Tools menu, click Internet Options. b. Click the Advanced tab. c. Scroll down to the Security section, and ensure that the Enable Integrated Windows Authentication (requires restart) setting is not selected. d. Click OK. e. Restart Internet Explorer. Troubleshooting Your Internet Explorer Configuration To use Internet Explorer for Windows Integrated Authentication you must ensure that the Java EE server on which you installed VSJ is in the Intranet Zone (on the Internet Explorer Security tab). This should be the case for most default setups, but may not be if one of the following is true: The domain name of the Java EE server on which VSJ is installed is different from the domain name of your desktop machine. You have modified the Intranet Zone settings. If your server is not part of the Intranet Zone then Windows Integrated Authentication will fail and a login dialog box will display. 26

Preparing Your Deployment Environment for VSJ If this occurs, perform the following steps: 1. In Internet Explorer, on the Tools menu, click Internet Options. 2. Click the Security tab. 3. Click the Local intranet icon and then click Sites. 4. Click Advanced. 5. Enter the name of your server, and then click Add. 6. Click OK. If you are sure that your server is part of the Intranet Zone, but a login dialog box is still displayed, do the following to check that Windows Integrated Authentication is being used in the Intranet Zone. 1. In Internet Explorer, on the Tools menu, click Internet Options. 2. Click the Security tab. 3. Click the Local intranet icon, and then click Custom Level... 4. Scroll down the Security Settings to the User Authentication section, and then select the Automatic logon only in Intranet Zone option. If Windows Integrated Authentication is still failing then you may have incorrectly set up the SPN for VSJ (See ). See Maintenance and Troubleshooting for other possible problems. Creating Keytab Files VSJ supports two mechanisms for storing key information required to authenticate users - setting a password and using keytab files. See Keytabs and Passwords for more information on each method. To create a keytab file and use this with VSJ: 1. Generate keytab files for each service that requires authentication. This can be done with the tools included with the VSJ release. The following examples show how to create a keytab using the tools on Windows and Unix. The keytab will contain two keys, one RC4 and one DES for the SPN of HTTP/host.domain@realm with a key version number of -1 (a value which acts as a wildcard). Example of creating a keytab on Unix: /opt/vsj-3.0/bin $./jkutil.sh jktutil (type '?' for help): add_entry -password -p HTTP/host.domain@REALM -k 255 -e rc4-hmac 27

Vintela Single Sign-on for Java from Quest Software Password for HTTP/host.domain@REALM: jktutil (type '?' for help): add_entry -password -p HTTP/host.domain@REALM -k 255 -e des-cbc-crc Password for HTTP/host.domain@REALM: jktutil (type '?' for help): list Slot KVNO Principal ---- ---- -------------------- 1 255 HTTP/host.domain@REALM 2 255 HTTP/host.domain@REALM jktutil (type '?' for help): write_kt -o http_host.keytab jktutil (type '?' for help): quit /opt/vsj-3.0/bin $./jklist.sh -e -k http_host.keytab Keytab name: FILE:http_host.keytab KVNO Principal EncType ---- -------------------- ----------- -1 HTTP/host.domain@REALM rc4-hmac -1 HTTP/host.domain@REALM des-cbc-crc /opt/vsj-3.0/bin $ Example of creating a keytab on Windows: C:\VSJ_3.0\bin> set JAVA_HOME=C:\jdk-1.4 C:\VSJ_3.0\bin> jktutil.bat jktutil (type '?' for help): addent -password -p HTTP/host.domain@REALM -k 255 -e rc4-hmac Password for HTTP/host.domain@REALM: jktutil (type '?' for help): addent -password -p HTTP/host.domain@REALM -k 255 -e des-cbc-crc Password for HTTP/host.domain@REALM: jktutil (type '?' for help): list Slot KVNO Principal ---- ---- -------------------- 1 255 HTTP/host.domain@REALM 2 255 HTTP/host.domain@REALM jktutil (type '?' for help): wkt http_host.keytab jktutil (type '?' for help): quit C:\VSJ_3.0\bin> jklist.bat -e -k http_host.keytab Keytab name: FILE:http_host.keytab KVNO Principal EncType ---- -------------------- ----------- -1 HTTP/host.domain@REALM rc4-hmac -1 HTTP/host.domain@REALM des-cbc-crc V:\VSJ_3.0\bin> 28

Preparing Your Deployment Environment for VSJ 2. When configuring an application for VSJ you will need to set the idm.keytab parameter (See Appendix A). The idm.keytab parameter value should point to the keytab file you generated for this service when you set up the application server. 3. Copy the generated keytab from Step 1 to the location specified by the idm.keytab parameter. The new keytab contains sensitive information that could be used to subvert the security of your VSJ installation so make sure that you set appropriate access permissions on this file, and do not send it over unsecured networks unencrypted. 29

Vintela Single Sign-on for Java from Quest Software 30

3 Deploying VSJ JBoss Edition Overview Installing VSJ JBoss Edition Configuring the VSJ Examples Deploying Web Components Using VSJ JBoss Edition Setting Up Logging Using VSJ Credential Delegation Cross-Domain Issues

Vintela Single Sign-on for Java from Quest Software Overview This chapter describes how to install VSJ JBoss Edition and then build SSO solutions using VSJ-protected Servlets and JSPs. It also shows how to extend a Servlet/JSP to support credential delegation for authenticating to other services such as ASP applications on an IIS Web server, as well as how to set up audit logging. Cross-Domain Issues describes some of the issues that should be considered when clients reside in a different Active Directory domain from the application server where VSJ is installed. Installing VSJ JBoss Edition To obtain a license for VSJ This distribution requires a VSJ license and does not include one; you must supply one yourself, as described below. The license is packaged as a JAR file so that it can be installed the same way VSJ's other JAR files are installed. Evaluation licenses are available by filling out the VSJ evaluation download form. You will receive an E-mail message that includes the license jar file as an attachment. Some E-mail clients rename the attachment to vsj-license.zip; in this case you may have to re-rename the saved file to vsj-license.jar Once you have a current license jar, add it to the lib/ directory alongside the other VSJ libraries. To install the VSJ components using Ant 1. If you have Apache Ant installed, you can run the deployment script to install VSJ libraries. 2. Edit the build.properties file (in the top-level directory of the VSJ JBoss distribution) and set the following properties: jboss.home The directory of your JBoss installation (for example: C:/jboss-4.0.5.GA) jboss.server The JBoss server configuration under which you want to run VSJ (for example: default) 3. Run ant deploy_vsj. 4. Restart JBoss. OR 32

Deploying VSJ JBoss Edition To copy the VSJ libraries to the appropriate location manually 1. Copy the following jar files to ${jboss.home} /server/${jboss.server} /lib directory (where jboss.home and jboss.server are as described above): lib/vsj-jboss-3.2.jar lib/vsj-license.jar thirdparty/lib/jcifs-1.1.9.jar thirdparty/lib/jldap.jar 2. Restart JBoss. To complete the installation JBoss has a configuration parameter for the maximum size of an HTTP header. By default it is 4096, which is too small for some HTTP Negotiate auth headers generated by Internet Explorer/Active Directory, especially those for users with a large number of group memberships. The configuration parameter maxhttpheadersize should be changed in ${jboss.home}/server/${jboss.server}/deploy/jbossweb-tomcat55.sar/server. xml (where jboss.home and jboss.server are as described above, note: path may vary slightly depending on version of JBoss). Configuring the VSJ Examples The distribution contains a number of examples demonstrating how to use VSJ JBoss Edition. To configure the examples, edit the sample vsj.properties file in the examples/ directory and configure the following parameters. This properties file is used as the configuration for all examples. idm.princ, idm.realm These parameters should be set to the Kerberos service principal name and the Active Directory domain to be used for authentication respectively. The combination of idm.princ@idm.realm should match the value that you set as the primary SPN when preparing your deployment environment. For example: 33

Vintela Single Sign-on for Java from Quest Software For Primary SPN: HTTP/host.domain.com@DOMAIN.COM Use values: idm.princ: HTTP/host.domain.com idm.realm: DOMAIN.COM idm.password / idm.keytab The idm.password parameter should be set to the password of the Kerberos service principal specified by idm.princ and created when setting up your VSJ deployment environment. VSJ will create an in-memory keytab using this password. Alternatively, idm.keytab can be used to specify a file keytab containing the key for the service principal. idm.allowunsecured Specifies whether to allow authentication over HTTP (rather than requiring HTTPS). This option can be set to true for development and testing but it is strongly recommended that it is not set in a production environment unless there is a very low risk of an attacker accessing the communication channel between the client and server. The default is false. idm.ad.qualifyuserprincipal idm.ad.site idm.allowntlm Fully qualify the authenticated user name returned by VSJ. For example, append the Active Directory domain name. The default is false. The Active Directory site in which this server should be placed. Specifies whether to allow fallback to NTLM authentication. This is required if you want to use VSJ with pre-windows 2000/XP Internet Explorer browsers which do not support SPNEGO. The default is false. Once these parameters are configured, you can build and deploy the examples. See the README files in each example s individual directory for more specific details. The recommended example for getting started is the 'simple' example. 34

Deploying VSJ JBoss Edition Deploying Web Components Using VSJ JBoss Edition To deploy web components using VSJ JBoss Edition 1. Create a new file called vsj.properties, and set your VSJ configuration properties as required. For example: # The Active Directory domain to be used for authentication. idm.realm = EXAMPLE.COM # The Active Directory service principal. idm.princ = HTTP/appserver.example.com ## Must configure one of: (a) idm.keytab, (b) idm.password # The keytab file of the service principal specified above. #idm.keytab= # The password of the service principal specified above. idm.password=password See Appendix A for the complete set of VSJ configuration parameters. 2. Create a login-config.xml file as follows: 35

Vintela Single Sign-on for Java from Quest Software This file is based on the ${jboss.home}/server/${jboss.server} /conf/login-config.xml which sets up the configuration for the security domains available to applications running in the server. This file basically hooks up a security domain to the VSJ login module(s). The "name" attribute on the "application-policy" element (in this case "vsj-app") specifies the name of the security domain. The name is used to tie the security domain to the web application. This custom login-config.xml is added to the root directory of your EAR file, which must be configured to use dynamic login configuration. The JBoss admin guide has more details on how to do this, but the basic files/changes required to do so are here. eg. meta-inf/jboss-app.xml <jboss-app> <module> <service>login-service.xml</service> </module> </jboss-app> eg. login-service.xml <server> <mbean code="org.jboss.security.auth.login.dynamicloginconfig" name="simple_ex:service=dynamicloginconfig"> <attribute name="authconfig">login-config.xml</attribute> <depends optional-attribute-name="loginconfigservice"> jboss.security:service=xmlloginconfig </depends> <depends optional-attribute-name="securitymanagerservice"> jboss.security:service=jaassecuritymanager </depends> </mbean> </server> Alternatively, the ${jboss.home}/server/${jboss.server} /conf/login-config.xml can be modified directly. This configuration change will be app-server wide, but in this case dynamic login configuration won't be necessary. 3. Configure the web application for security by adding constraints to the web deployment descriptor. You need to modify the web.xml in the WEB-INF directory of the web application you are securing to add in the following: <security-constraint> <web-resource-collection> <web-resource-name>all resources</web-resource-name> <description>protects all resources</description> <url-pattern>/*</url-pattern> </web-resource-collection> <auth-constraint> <role-name>webappuser</role-name> </auth-constraint> 36

Deploying VSJ JBoss Edition </security-constraint> <security-role> <role-name>webappuser</role-name> </security-role> The "security-constraint" section is what is used to define what resources in the web application are protected. You can have multiple security-constraint elements in the web.xml that have different protections for different resources. You have to have at least one web-resource-collection element to specify what this constraint it protecting. The "url-pattern" element specifies the URL pattern to protect. The example above protects _all_ resources in the web application. The auth-constraint element specifies which roles have access to the protected resource. The example just specifies one role, but multiple roles can be included by specifying additional role-name elements. Role names and mappings can be specified in the rolemapping.properties file in the format "rolename=user/group1[,user/group2...]". For example: Role1=user@EXAMPLE.COM Role2=group@EXAMPLE.COM 4. Configure the jboss-web.xml file to point to the "vsj-app" application. Add/edit the jboss-web.xml in the WEB-INF directory of the web application you are securing to add the following in the "jboss-web" element: <jboss-web> <security-domain flushonsessioninvalidation="true"> java:/jaas/vsj-app </security-domain> </jboss-web> This element tells JBoss AS to connect the web application to the "vsj-app" security domain we specified in the login-config.xml file earlier. JBoss AS exposes security domains via JNDI by prepending "java:/jaas/" to the name element in the application-policy element in the login-config.xml file. 37

Vintela Single Sign-on for Java from Quest Software 5. Configure the context.xml file to use the VSJ JBoss Edition valves. Add/edit the context.xml in the WEB-INF directory of the web application you are securing to add the following in the "jboss-web" element: <Context> <Valve classname="com.quest.vsj.jboss.auth. VsjAuthValve" /> <!-- This extra valve is required only if NTLM authentication is used --> <Valve classname="com.quest.vsj.jboss.auth. VsjFauxNtlmValve" /> </Context> 6. Rebuild your VSJ-enabled web application and deploy. Setting Up Logging VSJ JBoss Edition integrates with the Log4J logging framework used by JBoss. The Log4J configuration file can be found at ${jboss.home}/server/ ${jboss.server}/conf/log4j.xml. The easiest way to enable VSJ logging is to edit the Log4J configuration file and create two new categories: <category name="com.wedgetail"> <priority value="debug"/> <appender-ref ref="file"/> </category> <category name="com.quest"> <priority value="debug"/> <appender-ref ref="file"/> </category> This will output VSJ log messages at a DEBUG level to the default JBoss log file. More details on logging levels and how to configure Log4J can be found at http://logging.apache.org/log4j/docs Additional logging can be switched on by starting JBoss with the VSJ debug flags: set JAVA_OPTS=%JAVA_OPTS% -Djcsi.kerberos.debug=true -Didm.spnego.debug=true 38

Deploying VSJ JBoss Edition Using VSJ Credential Delegation One of the most powerful features of VSJ is its support for credential delegation. This feature allows Java EE components deployed with VSJ to use credentials provided by the client to authenticate to other services on the client's behalf. This works as shown in Figure 1. Delegation does not work for users authenticated using NTLM. Figure 1: Credential Delegation 39

Vintela Single Sign-on for Java from Quest Software Delegating to Another Web Resource Using SPNEGO This section demonstrates how to use the delegated credential obtained above to authenticate to another Web resource that uses SPNEGO authentication. This could be another JSP or Servlet running VSJ on a different application server, or an ASP or.net application running on IIS. This example assumes that you are familiar with the basics of how the SPNEGO protocol operates (see SPNEGO and Internet Explorer for a refresher). The first step is to create a new SpnegoClientManager, using a default GSSManager object, which can then be used to create initiator (client-side) objects such as GSSName or GSSContext. Security.insertProviderAt(new GSSKrb5ProviderForJBoss(), 4); spnegomanager = new SpnegoClientManager(GSSManager.getInstance()); Oid krb5principalnametype = new Oid("1.2.840.113554.1.2.2.1"); peername = spnegomanager.createname("http/" + hostname, krb5principalnametype); The standard mechanism for using SPNEGO over HTTP uses the WWW-Authenticate and Authorization fields of the HTTP headers with the Negotiate authentication type to perform this task. VSJ provides a utility class called HttpTokenTransport which simplifies this task, as shown below: String serviceurl = "http://" + hostname + ":8080/service2"; HttpTokenTransport trans = new HttpTokenTransport(serviceURL); The only requirement for initializing the HttpTokenTransport is a URL for the service to which you wish to send the SPNEGO enhanced request. Once the transport mechanism has been built, you can authenticate to the new service using the following code fragment: // Perform authentication using context initialization loop. byte[] intoken = new byte[0]; while (!cl.isestablished()) { byte[] outtoken = cl.initseccontext(intoken, 0, intoken.length); } if (outtoken!= null) { intoken = trans.sendandreceive(outtoken); } 40

Deploying VSJ JBoss Edition The code loops around, generating and accepting SPNEGO tokens which are sent and received from the HttpTokenTransport.sendAndReceive(byte[]) method. Once authenticated you can use the HttpTokenTransport.getInputStream() method to obtain the data returned in the HTTP response as follows: // Get an InputStream to allow us to read the data returned in the HTTP response InputStream in = trans.getinputstream(); // Read the response data from the input stream... // Close the HTTP connection trans.close(); For a full example of a Servlet demonstrating credential delegation to retrieve Web resources, see the Delegation example included in your VSJ installation. Cross-Domain Issues VSJ can be used in an environment where clients (either Internet Explorer or Java clients written to the VSJ API) can reside in a different Active Directory domain from the application server where VSJ is installed. There are a few requirements for this to work: All the Active Directory domains where client and server can reside are running Active Directory as their KDC (in particular, the client and server domains cannot be linked by an "external trust" such as an MIT realm). The machines running Active Directory may be either Microsoft Windows 2000 Server or Windows Server 2003. If the requirements for cross-forest trust are met (typically all Active Directory domain controllers are running on Windows Server 2003 machines running at "Windows Server 2003" functionality level consult the Windows Server 2003 help files for more details), then the client and server domains may be located in different (but trusting) forests. If at least one of the domain controllers is running Windows 2000 Server, then the client and server domains must be in the same forest (but may be any leaves in any tree in that forest). 41

Vintela Single Sign-on for Java from Quest Software Client-Side Configuration Internet Explorer No additional configuration is required for Internet Explorer clients. If a user logged into a machine in Windows domain A points their browser to a VSJ-protected servlet running on a machine in Windows domain B, then Internet Explorer will automatically determine the sequence of KDCs which are needed to produce a service ticket for the server, and make the appropriate ticket requests. Basic Fallback If a client is using a HTTP client (for example, a browser) which doesn't support the SPNEGO authentication method, then VSJ will fall back to using basic authentication the browser will display a dialog box asking for a username and password. If a client is using a principal residing in a different domain from the server, then either: In the login dialog box which appears when basic authentication is requested, append @<client-domain-here> to the username, for example, myuser@example.com. If the filter/servlet initialization parameter idm.fallbackcrossrealm is set to true (the default is false), the authentication filter/servlet will attempt to guess the client's domain from the domain part of the hostname returned by ServletRequest.getRemoteAddr(), and the user is not required to append the domain to their username. 42

4 VSJ Federation for JBoss Introduction Features Prerequisites Installation Configuration

Vintela Single Sign-on for Java from Quest Software Introduction VSJ JBoss Federation provides single sign-on for web applications in a Microsoft ADFS (Active Directory Federation Services) environment. Features Provides integration of standard web applications, independent of container and operating system. Extends single sign-on experience to extranet and Internet applications by allowing users to leverage their ADFS credentials. Standards based, uses Passive Requestor profile of WS-Federation, SAML to represent the claims and HTTP 1.1 for message transport. The servlet filter is fully compliant with version 2.3 of the Java Servlet Specification. Fully extensible allowing custom integration for security processing of the Federation token. Allows application developers to take advantage of the Federation environment by supporting access to the authentication information (federation token), the SAML claims and by supporting the standard methods isuserinrole() and getremoteuser() of HttpServletRequest. Utilises the Application Container framework to cache authentication information across accesses avoiding the high network latency costs involved in re-authenticating. Produces fully configurable audit trail and logging information. 44

VSJ Federation for JBoss Prerequisites This version of VSJ Federation requires the following libraries. Apache XML Security (included) Apache Commons Logging (included) OpenSAML (included) VSJ Federation also requires an ADFS server (Windows Server 2003 R2). Installation To install the VSJ Federation components for JBoss 1. If you have Apache Ant installed, you can run the deployment script to install VSJ libraries. 2. Edit the build.properties file (in the top-level directory of the VSJ JBoss distribution) and set the following properties: jboss.home -- The directory of your JBoss installation (for example: C:/jboss-4.0.5.GA) jboss.server -- The JBoss server configuration under which you want to run VSJ (for example: default) 3. Run ant deploy_vsj-federation. 4. Restart JBoss. OR To copy the VSJ federation libraries to the appropriate location manually 1. Copy the following jar files to ${jboss.home}/server/${jboss.server} /lib directory (where jboss.home and jboss.server are as described above): lib/vsj-license.jar federation/lib/vsj-jboss-federation-3.2.jar federation/thirdparty/lib/opensaml-1.1.jar federation/thirdparty/lib/xmlsec-1.3.0.jar 2. Restart JBoss. 45

Vintela Single Sign-on for Java from Quest Software Configuration The following parameters are available for configuring the VSJ Federation servlet filter. Parameter Description Default Req d fsproxy applicati onuri returnurl The URL of the resource federation server, For example: https://resource-fs.resource.p artner/adfs/ls/clientlogon.asp x The URL of the application that is being federated. This will match the URL configured in the Active Directory Federation Service. For example: http://master.resource.partner :7001/vsj-federation/authentic ated/index.jsp Where responses (from the federation servers) should be directed to if different from the above applicationuri parameter. X X signoutim age fscertifi cate accepttok encert clockskew Specifies the location of the signout image, requested by the default Windows 2003 Federation Server configuration on signout. Specifies the location of the resource federation server base64 encoded certificate. Required, unless accepttokencert is set to true (not recommended). Specifies whether to accept certificates presented in the federation token as trusted. Defaults to false. The amount of time in minutes that is allowed for differences between computer times. plus_green.gif false 5 46

VSJ Federation for JBoss Parameter Description Default Req d loggingpr operties Specifies where to find the log4j configuration file. Defaults to log4j.properties. log4j.properties 47

Vintela Single Sign-on for Java from Quest Software 48

5 Using the JKTools Overview The JKTools Examples

Vintela Single Sign-on for Java from Quest Software Overview Vintela Single Sign-on for Java includes several tools which enable you to create, manipulate and display Kerberos credential caches and keytab files: jkinit authenticate and request a network credential jklist display credential cache or keytab contents jktutil create, manipulate and display keytabs The JKTools The tools are Java-based and will therefore run on z/os, Linux, and Unix computers as well as Microsoft Windows platforms. When the jkinit and jklist tools are run on a Windows platform they operate on the Windows LSA (Local Security Architecture) credential cache, while under Unix they operate on standard files in the filesystem. The tools also operate on files created by utilities from the MIT Kerberos distribution, an implementation commonly found on Linux and Unix installations. Each tool has help embedded so that invoking the tool with the -help parameter will display summary information about the parameters the tool supports. The manual pages are included in the distribution and contain detailed information about the use of each of these tools. jkinit The jkinit tool is used to request and store a credential from a Microsoft Active Directory. This is located on the Domain Controller responsible for the requested domain (or realm). After a successful authentication a credential is returned which is then stored in a credential cache. The credential can then be used in later operations. jklist The jklist tool is used to display the contents of credential caches and keytabs including the key enycryption types, the ticket flags and principal name. 50

Using the JKTools jktutil The jktutil tool allows the user to create keytab entries specifying the principal name, encryption type and key version number. The entries can then be saved or appended to a keytab file. jktutil can also read and write keytab files, which enables merging of keytabs and their entries. Examples Authenticate and Request a Default Credential $ jkinit.sh alice@example.com Password for alice@example.com: ****** Authenticate and Request a forwardable and proxyable credential $ jkinit.sh -f -p alice@example.com Password for alice@example.com: **** List the Default Credential Cache Showing the Key Encryption Type $ jklist.sh -e TicketCache: FILE:/tmp/krb5cc_1000 Default principal: alice@example.com Valid starting Expires Service Principal 02/14/2005 13:25:23 02/14/2005 23:25:23 krbtgt/example.com@example.com Etype: (skey) rc4-hmac List the Default Credential Cache Showing the Ticket Flags $ jklist.sh -f TicketCache: FILE:/home/alice/.krb5cc Default principal: alice@example.com Valid starting Expires Service Principal 51

Vintela Single Sign-on for Java from Quest Software 05/26/2005 09:11:01 05/26/2005 19:08:55 HTTP/host.example.com@EXAMPLE.COM Flags: OA 05/26/2005 09:29:34 05/26/2005 19:29:33 krbtgt/example.com@example.com Flags: FPIA Create a Keytab with an rc4-hmac Key $ jktutil.sh jktutil (type '?' for help): add_entry -password -p alice@example.com -k 255 -e rc4-hmac Password for alice@example.com: ****** jktutil (type '?' for help): list Slot KVNO Principal ---- ---- -------------------- 1 255 alice@example.com jktutil (type '?' for help): write_kt alice@example.keytab jktutil (type '?' for help): quit List a Keytab Showing the Encryption Types $ jklist.sh -e -k alice@example.keytab Keytab name: FILE:alice@EXAMPLE.keytab KVNO Principal EncType ---- -------------------- ----------- -1 alice@example.com rc4-hmac Merge Two Keytabs $ jktutil.sh jktutil (type '?' for help): rkt alice@example.com jktutil (type '?' for help): wkt -o all@example.com jktutil (type '?' for help): rkt bob@example.com jktutil (type '?' for help): wkt -a all@example.com jktutil (type '?' for help): rkt all@example.com jktutil (type '?' for help): list Slot KVNO Principal ---- ---- -------------------- 1-1 alice@example.com 2-1 bob@example.com jktutil (type '?' for help): quit 52

6 Security Issues Overview Summary of Basic Recommendations Client Issues SPNEGO/Windows Integrated Authentication Session IDs Active Directory Permissions Basic Fallback Keytabs and Passwords Authorization Denial of Service Auditing NTLM Authentication

Vintela Single Sign-on for Java from Quest Software Overview Like any security software, VSJ requires that it be configured and deployed correctly to be secure. VSJ is designed with a secure by default policy. However, developers should be aware of certain issues that need to be addressed to achieve this in practice. This section outlines the mechanisms in VSJ used to achieve secure operation, and outlines some areas that may need special attention. This chapter assumes familiarity with basic security concepts, Kerberos, the HTTP protocol and Java EE application configuration. Summary of Basic Recommendations Limit the use of basic fallback where possible (disabled by default). Limit the lifetime of sessions, and ensure that session IDs are "unguessable". Ensure that the authorization rules limit users to their least privilege. If using basic fallback, configure Active Directory to lock out users after some specified number of failed logins. Do not use basic fallback where there is a high risk of Denial of Service attacks, or provide other countermeasures to prevent them. Enable logging to at least the WARN level. Client Issues Cookies Unlike some Web SSO implementations, VSJ does not use cookies to store encrypted passwords. Instead it relies on the caching of Kerberos tickets to provide SSO functionality. For Microsoft Windows clients, these credentials are stored in memory, and never written to disk, so the chance of compromise is very low. However, cookies are commonly used to store session ID state (see Session IDs on page 56). 54

Security Issues Because authentication in VSJ is bound to the session state, these cookies present a security risk if they are leaked or sent in clear across the network. This means that communication between the browser and application server should always be done via SSL to protect these session IDs. Most application servers use transient cookies for tracking session state that are only stored in memory by the browser, and will not be written to disk. This means there is a low risk of compromise of the session ID information from the client. Alternatively, you could develop your applications to use URL rewriting instead of cookies for session state, which has the advantage that it will work for all browsers, regardless of whether they have cookies enabled or not. Caching of Passwords for Basic Fallback For non-internet Explorer clients, or clients that do not support Kerberos, VSJ provides a mechanism for authenticating via the standard basic HTTP authentication mechanism. This sends a password in clear over HTTP, which is then used by the VSJ-protected Filter/Servlet to perform a standard Kerberos authentication. Because most clients support password managers and/or caching of passwords when using basic authentication, care should be taken to ensure that this information is not leaked or sent over the network. Again, this means ensuring that the password is not saved on a network volume, and that authentication should be done over SSL (see Basic Fallback). Consult your browser documentation to ensure that it is configured appropriately. SPNEGO/Windows Integrated Authentication VSJ uses the SPNEGO protocol to perform Windows Integrated Authentication via HTTP. This protocol uses the Kerberos GSS-API protocol to mutually authenticate clients and servers via HTTP headers. While the GSS-API protocol itself is secure, this protocol does not ensure that the content of the HTTP request is securely bound to the message. This means that a man-in-the-middle attack could be used to modify the HTTP content while keeping the authentication headers intact. For this reason, unless the risk is very low, you should ensure that authentication is done over SSL. 55

Vintela Single Sign-on for Java from Quest Software Lifetime of Authentication Because SPNEGO requires two round trips to authenticate requests, it would be too expensive to perform an authentication for each request. Instead, applications supporting SPNEGO will bind the authentication to a session or a connection. Note that authentication and reauthentication is performed transparently by Internet Explorer, and the user is not required to reenter their password. When Windows Integrated Authentication is done to IIS using Internet Explorer, the authentication is done once per connection (HTTP 1.1 allows multiple requests to be performed over the same connection). As long as a connection is kept open, the user will not have to reauthenticate. For VSJ, authentication is bound to a Java EE session (that is, once authenticated for a particular session, the user is not required to authenticate for the lifetime of that session, or until their service ticket expires). The session has a lifetime defined by the Java EE configuration. While this means that a user will have to reauthenticate for each application (and each new session), the lifetime of these authentications may be potentially longer. In practice, this will make little difference as the connections should be protected by SSL, meaning that there is little opportunity for an attacker to obtain a session ID or hijack a TCP connection. However, the distinction needs to be considered when thinking about the appropriate lifetime of Java EE session IDs (see Session IDs below). Session IDs VSJ binds the authentication of a user to a Java EE session ID. It does this by authenticating the user via SPNEGO (or the basic fallback mechanism) and then storing the user's Kerberos ticket and other associated information in the Java EE session information. For subsequent requests that use this session ID, VSJ checks that the information is still valid and lets the request through without requesting reauthentication. This means that an attacker who is able to sniff the session ID, or obtain it by "guessing" will be able to subvert the security of VSJ. For this reason, SSL should always be used to protect the session, and you should ensure that the session IDs used by your application server are random and large enough that they cannot be guessed by brute force. 56

Security Issues In addition, you should ensure that the mechanism that your application server uses to ensure persistence of session information does not involve sending the session ID in the clear over the network. This could be the case, for example, if JDBC to a database on another machine or a network file system is being used for persistence. Lastly, because of the sensitivity of session ID information, VSJ ensures that it does not log session IDs, but instead logs the MD5 hash of the ID. This allows events to be correlated across sessions, without the risk of the session ID being leaked (for example, if you are logging over a network, or to a network volume). See Auditing for more details on logging. Active Directory Permissions VSJ requires read access to a number of attributes in Active Directory. This section details which attributes and permissions are required. Access to these elements is enabled by default in Active Directory. Setting these permissions is only required if you have modified these defaults. The following containers are examined: RootDSE Configuration Partitions User/Group The RootDSE container is examined for the following attributes: rootdomainnamingcontext defaultnamingcontext configurationnamingcontext supportedsaslmechanisms The Configuration container is examined for the following attributes: objectclass=crossrefcontainer 57

Vintela Single Sign-on for Java from Quest Software The Partitions container is examined for the following attributes: netbiosname=${domain} dnsroot The top-level domain container is examined for the following attributes: ntmixeddomain User/Group Accounts are examined for the following attributes: useraccountcontrol grouptype userprincipalname serviceprincipalname distinguishedname objectclass cn samaccountname name lastlogon badpwdcount objectsid sidhistory primarygroupid The property sets for the attributes listed above are as follows: Attribute userprincipalname serviceprincipalname distinguishedname objectclass cn samaccountname Property Set PublicInformation PublicInformation PublicInformation PublicInformation PublicInformation GeneralInformation 58

Security Issues Attribute Property Set member grouptype useraccountcontrol ntmixeddomain rootdomainnamingconte xt defaultnamingcontext configurationnamingco ntext supportedsaslmechanis ms name lastlogon badpwdcount objectsid sidhistory primarygroupid dnsroot netbiosname Membership N/A N/A N/A N/A N/A N/A N/A N/A User-Logon User-Logon GeneralInformation GeneralInformation GeneralInformation N/A N/A For the normative reference on Active Directory property sets, see: http://msdn2.microsoft.com/en-us/library/ms683990.aspx Basic Fallback The basic fallback mechanism is provided to allow support for non-kerberized browser clients. It allows a simple username and password to be entered and a Kerberos login to be performed on the server. Some issues to do with caching of passwords on clients are described on page 55. The basic challenge uses the Active Directory domain in the realm part of the request, meaning that for browsers that cache passwords, the user will not have to reenter their password 59

Vintela Single Sign-on for Java from Quest Software for the lifetime of the cached password for any application that is using that Active Directory domain. However, unless the browser is running a password manager the cached password will disappear when the user closes their browser. This will result in them having to reenter their password the next time they connect to an application. Once VSJ has used the password to obtain the Kerberos ticket on the server, the password is disposed of. This limits the risk of a server compromise compromising a large number of passwords. It should be noted that the basic fallback mechanism provides an opportunity for an attacker to try to guess passwords for Kerberos users. VSJ does not do any checking for a number of bad logins (although it is possible to obtain the number of bad logins since the last login if a request is successful programmatically). For this reason you should consider configuring Active Directory to lock out users after a number of bad login attempts (see page 62 for Denial of Service risks associated with this approach). Keytabs and Passwords VSJ requires that the application be associated with a user account and provided with either a password, or a keytab file (see Creating Keytab Files for details) stored on the server. idm.password and com.wedgetail.idm.sso.password are intended to be convenient for initial setup and debugging in a test environment. Once VSJ is up and running happily with the password, we recommend using a keytab instead. Similarly, while the keytab file location is specified by a parameter in the deployment descriptor, it must be stored at an absolute location on the server, and not in the EAR/WAR file. This is because commonly there may be multiple copies of EAR/WAR files created by developers/deployers lying around with sensitive passwords in them, or they may be deployed in the clear over unsecured links. 60

Security Issues In all cases, care must be taken to ensure that applications that should not have access to this information are either not deployed on the same server, or access is prevented by enabling the Java security manager. If you choose to do the latter you will need to configure your Java security policy file to grant various permissions. Authorization Do You Need Authorization? Many Java EE developers are used to deploying applications and just creating a username and password for those users who need to access the application. However, with VSJ, unless you want everyone with a desktop login in your organization to access the application you will need to define some authorization groups to control access. Securing LDAP VSJ uses group information in the PAC of the service ticket to authorize users. However, this group information only lists the SIDs and not the names of the groups which are specified in the authorization policy. To resolve names, VSJ needs to contact Active Directory via LDAP. In most cases it only needs to do this once at load time, however if you are using some of the programmatic functions to access group information, this may also happen at run time. The information in the PAC is securely authenticated as part of the ticket. However, the mapping between SIDs and the group names they represent must be done securely. Otherwise, an attacker could substitute their own name for SID mappings and subvert the authorization mechanism. For this reason the connections between VSJ and the Active Directory LDAP servers need to be secured. By default, connections to Active Directory are secured using the standard SASL/GSS-API mechanism. 61

Vintela Single Sign-on for Java from Quest Software Using the "Principle of Least Privilege" The Principle of Least Privilege is a security maxim stating that users should only be given the least amount of privilege required, and no more. We recommend that you apply this principle when creating authorization policies using VSJ. Allocate a role to each task and map this to one or more groups managed in Active Directory. It is useful to use groups which are specific to your application to prevent the risk of a user inadvertently being added to a group so they may access an entirely different application. Denial of Service VSJ has a number of mechanisms to prevent Denial of Service (DoS) attacks. The most important is that no state information is stored on the server until the client has authenticated. In addition, VSJ limits the amount of communication that is required with back-end servers, and in most cases authentication and authorization can be performed locally without having to contact Active Directory. However, there are some issues that need to be considered to increase resistance to DoS attacks. These are discussed below. Basic Fallback Unlike Windows Integrated Authentication, the basic fallback mechanism requires communication with Active Directory to be performed by the server. Because of this, it can be exploited to mount a DoS attack by saturating the number of outgoing connections. A number of application servers can also be used to "amplify" an attack on Active Directory using this feature. For this reason, basic fallback should be disabled in situations where there is a high risk of DoS attacks, or other measures should be undertaken (such as using a firewall that drops a large number of connections, or increasing capacity). Session State Once authenticated, each VSJ session will store security information associated with the connection, including the user's ticket and delegated credential. It could be possible for an attacker who obtains a legitimate user's account to saturate the memory of an application server by making a large number of new requests to an application. However, this is a fairly low risk. Such an event would be indicated by a large number of logins from the same account in the audit logs, and could be effectively stopped by disabling the offending account. 62

Security Issues Auditing VSJ provides an auditing capacity with several different levels allowing effective diagnosis and recovery for security events. Setting Up Logging describes how to enable this logging facility. We recommend that the logging level be set to "WARN", which covers security sensitive events such as bad logins. If there is sufficient capacity and a low risk of a DoS attack on your logging system, you will also find INFO to be useful, as this logs information about successful requests. The audit logs contain the date, source IP, URL being accessed and, if appropriate, the MD5 hash of the session ID to allow effective correlation of events. NTLM Authentication VSJ provides support for the NTLM authentication mechanism when SPNEGO authentication is unavailable. This is of particular use for operating system / browser combinations that do not support SPNEGO (for example, Microsoft Windows 98 and Windows NT). What is NTLM? NT LanManager (NTLM) is a Microsoft proprietary authentication mechanism that is integrated into all of the Windows NT family of products. Like its predecessor, LanManager, NTLM uses a challenge response process (sometimes referred to as NTCR) to prove client identity without ever requiring a password or even a hashed password be sent across the network. It does this using a three-pass process consisting of: 1. Negotiation Send a list of security features supported by the client. 2. Challenge Send back a list of security features agreed upon by the server, as well as a challenge that only the client would know. 3. Authentication Respond to the server's challenge, and also send the username and domain information for the client. 63

Vintela Single Sign-on for Java from Quest Software Different Versions of NTLM Historically, the Microsoft Windows family of products have supported two variants of challenge/response authentication for network logons: LAN Manager (LM) challenge/response Windows NT challenge/response (NTLM version 1) The LM variant allows interoperability with the installed base of Windows 95, Windows 98, and Windows ME clients and servers. NTLM was designed to provide improved security connections between Windows NT clients and servers. Windows NT also supports the NTLM session security mechanism that provides for message confidentiality (encryption) and integrity (signing). Recent improvements in computer hardware and software algorithms have made these protocols vulnerable to widely published attacks for obtaining user passwords. To resolve these problems, Microsoft developed an enhancement, called NTLM version 2, that significantly improves both the authentication and session security mechanisms. NTLM 2 has been available for Windows NT 4.0 since Service Pack 4 (SP4) was released, and it is supported natively in Windows 2000. You can add NTLM 2 support to Windows 95 and Windows 98 by installing the Directory Services Client from the Windows 2000 CD-ROM. For more instructions, see: http://support.microsoft.com/default.aspx?scid=kb;en-us;239869 We recommend that you use NTLM v2 whenever NTLM is required for authentication. NTLM and Internet Explorer Internet Explorer permits four options for using the NTLM authentication mechanism: 1. Anonymous logon connect to a server without attempting to provide or send logon information 2. Automatic logon only in Intranet zone connect to a server by using your current session username and password, but only if the server is in your Local Intranet zone 3. Automatic logon with current username and password connect to a server by using your current Windows user name and password 4. Prompt for user name and password connect to a server by providing a user name and password when prompted 64

Security Issues We do not recommend using option 3 as a malicious Web site operator can trick Internet Explorer into responding to a NTLM challenge and obtaining the password by cracking the response. Alternatively, an attacker can send an email with a link back to the attacker's Web site, which sends an NTLM authentication challenge when the user clicks on the link. If the Internet Explorer has not been securely configured, the onsite server encrypts that challenge with the user s password hash as the key and sends it back as the response. The attacker may then be able to crack the user s internal domain password. We recommend that for your: Intranet zone (and perhaps Trusted sites zone, if you use that zone for business partners in an extranet scenario), you set Logon to Automatic logon only in Intranet zone. Internet and Restricted sites zone, you should use Anonymous logon or Prompt for user name and password. If you select Anonymous logon, Internet Explorer won t respond to authentication requests. If you select Prompt for user name and password, Internet Explorer won t automatically respond to authentication requests with the user s domain credentials; instead, Internet Explorer displays a window asking the user for credentials. 65

Vintela Single Sign-on for Java from Quest Software 66

7 Maintenance and Troubleshooting Overview Maintenance Troubleshooting

Vintela Single Sign-on for Java from Quest Software Overview This chapter discusses the common maintenance issues relating to a VSJ deployment and provides solutions to some common problems which may be experienced when configuring and deploying applications using VSJ. Maintenance This section discusses the maintenance issues relating to a VSJ deployment. Logging VSJ supports logging at different levels (see Setting Up Logging). For maintenance purposes, logging at WARN level is recommended, along with regular inspection of the generated log file. Regular inspection should alert the administrator to potential problems within VSJ. New Users / Groups Adding a new user or group to Active Directory should not impact upon the performance of VSJ so long as existing policy settings remain unchanged. Once a new user or group has been added to Active Directory, that user may be authenticated by VSJ through the existing mechanisms. Account Settings VSJ may cache information about user / group accounts for efficiency. For example, the groups that a user belongs to may be cached once that data has been obtained, and the authorization policy may be determined based on this (cached) data. If the group membership details of that user are updated dynamically, this may not be reflected in VSJ's cache, and subsequent authorization determinations may produce incorrect results. 68

Maintenance and Troubleshooting Network Topology Changes VSJ performs dynamic lookups when resolving services (such as finding the KDC for a realm, or domain controller for a domain) to hosts. Modifying the underlying network topology should therefore not present a problem for VSJ, although it should be noted that a lag between the time the topology has been modified and the time that dynamic lookups reflect this new topology may cause some connection timeouts. Troubleshooting This section provides solutions to some common problems which may be experienced when configuring and deploying applications using VSJ. General Problem: When connecting to the servlet an Error page is displayed indicating an Internal Server error. This error is due to either a configuration problem on the server, a misconfiguration of the client browser, or some other internal failure such as an incorrect response returned from a KDC. Depending on your application server, a more detailed message may be displayed in the error page, or you may need to look at the application server log files for the root cause. The following causes are noted below: Cause: Could not get service ticket for <principal>@<realm> This error will be shown in the application server's logs as: CryptoException: Integrity Check Fail It is indicative of a keytab that has been created with an incorrect password. To resolve the problem you should regenerate the keytab using the correct password. Cause 1: Error 500: Filter [authfilter]: com.wedgetail.idm.sso.authfilter was found, but is missing another required class. Java 2 Security has been enabled without a suitable policy file. Either disable Java 2 Security or contact us for help building a suitable security policy file. 69

Vintela Single Sign-on for Java from Quest Software Cause 2: Cause 3: [Servlet Error]-[Filter [authfilter]: could not be initialized]: com.dstc.security.kerberos.kerberosexception: key type mismatch This problem only occurs on Microsoft Windows 2003 when a service request is sent in an ENC type that is different from the service ticket returned. It is only a problem with Memory keytabs. One solution is to change the Active Directory user account for the service so that the Use DES Only option is checked. Alternatively, you could use a file keytab. ConfigException: Unable to resolve Domain Controller for NTLM This problem occurs when VSJ cannot automatically establish the NTLM domain controller using the DNS. One possible solution to this problem is to manually specify the domain controller to be used. You can do this by adding the jcifs.http.domaincontroller parameter to the Web application s deployment descriptor (web.xml), i.e.: <init-param> <param-name>jcifs.http.domaincontroller</param-name> <param-value>mydomaincontroller</param-value> </init-param> 70

Maintenance and Troubleshooting Active Directory Problem: I created a new service principal, but then I received an "Integrity check failure" message. Cause: Sometimes Active Directory doesn't set the keys properly for a newly created service principal until you log in to that account once. Log in as that user, log out and then restart your application server software. Browsers Problem: VSJ returns the following HTTP error response codes: 401 (UNAUTHORIZED) -- request is not authorized 403 (FORBIDDEN) -- access to requested resource is forbidden 500 (INTERNAL SERVER ERROR) -- internal server error. Cause: Error responses from VSJ will typically return no content, and display on the client browser as an empty page. If you wish to display different content for such errors, or to take some other action based on such errors, add an <error-page> element to web.xml. For example: <error-page> <error-code>401</error-code> <location>/errors/401.html</location> </error-page> Internet Explorer Browsers Problem: When using Internet Explorer, you are presented with a username and password dialog box rather than being automatically logged in. Cause: This occurs when Internet Explorer does not recognize the hostname as being part of the Intranet Zone. You may have not configured Internet Explorer to use Windows Integrated Authentication. Do the following: For SPNEGO, check that your Internet Explorer version is 5.5 or greater. Follow the steps in Troubleshooting Your Internet Explorer Configuration to ensure that Internet Explorer has been correctly configured to support SPNEGO. 71

Vintela Single Sign-on for Java from Quest Software Problem: The following error is encountered when authenticating against the server: [ERROR]: Provider protocol error: com.wedgetail.idm.spnego.server.spnegoexception: java.lang.securityexception: Unsupported keysize or algorithm parameters Cause: This problem is encountered when using a version of Internet Explorer that does not have the High Encryption Pack installed. There are two workarounds: Install the appropriate High Encryption Pack for your Internet Explorer browser (see Setting Up Internet Explorer for SSO for more information). Install the Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files (US_export_policy.jar and local_policy.jar). You can download them from http://java.sun.com/j2se/1.4/download.html. Problem: Internet Explorer 5.5 displays DNS error page Cause: If the user account is disabled at any time, Kerberos will be unable to renew credentials for the user. Problem: Internet Explorer 6 displays a blank page Cause: Cause: Windows Integrated Authentication is not enabled. See Setting Up Internet Explorer for SSO. You are going through a proxy that does not support session-based authentication. Disable the proxy in your browser. Non-Internet Explorer Browsers Problem: When using a non-internet Explorer browser, rather than presenting a username and password dialog box, the browser gives an error message indicating that the authentication mechanism is not supported. Cause: The filter has not been configured to allow fallback authentication for non-internet Explorer browsers. You need to ensure that the filter is configured with the idm.allowfallback option set to true. Otherwise, non-internet Explorer browsers will not be supported. 72

Maintenance and Troubleshooting Authentication Problem: Servlet/JSP configured with AuthFilter fails to start. This is commonly caused by a configuration problem with the AuthFilter filter. You will need to check your application servers log file to determine the root cause. Possible log entries are: Cause: Cause 4: Cause 5: Cause 6: Cause 7: ServletException: Need to set idm.realm. The idm.realm parameter determines the Kerberos realm that will be use by the SSO solution to authenticate clients. It must be set in the deployment descriptor. ConfigException: Only one of "idm.keytab" or "idm.ccache" or "com.wedgetail.idm.sso.password" should be specified. The SSO solution supports either user-to-service mode (using a keytab), or user-to-user mode (using a credential cache). Only one of idm.keytab or idm.ccache or com.wedgetail.idm.sso.password may be specified. In most cases you will want user-to-service. ConfigException: Must configure either idm.ccache or idm.keytab or com.wedgetail.idm.sso.password. The deployer must specify either the credential cache or keytab to use. Config Exception: Must use a keytab if idm.allowfallback configured. The idm.allowfallback parameter allows the deployer to specify whether the AuthFilter filter should allow users to authenticate using basic authentication and act as an authentication proxy to perform a Kerberos login to the KDC on the user's behalf. If fallback mode is enabled, then user-to-service mode must be used, and hence a keytab must be specified via the idm.keytab parameter, or the keytab password specified by the com.wedgetail.idm.sso.password system property. ConfigException: <keytab> not found The keytab specified by idm.keytab could not be loaded. The keytab must be at the path specified. Ensure that the file is present and that the correct path and file name is specified in the idm.keytab parameter. 73

Vintela Single Sign-on for Java from Quest Software Cause 8: ConfigException: No keytab entries for <principal>@<realm> in <keytab> The specified keytab did not contain any keys for the principal that was configured using idm.principal and idm.realm. If idm.principal was not specified then entry will be of the form: HTTP/<host.domain>@<realm> Where <host> is the fully qualified name of the host on which the filter is deployed. You can use the Kerberos klist command to check the keytab entries. Under UNIX this command is supplied as part of the Kerberos distribution and under Windows is supplied with JDK 1.4. Ensure that there is an entry for the specified principal. Cause 9: ConfigException: Could not load keytab "<keytab>" The keytab could not be loaded for some reason. Possibly this was due to corruption, or an incorrectly formatted file. Cause 10: ConfigException: Invalid KDC host "<kdc>" The hostname for the KDC specified by the parameter idm.kdc is invalid. Ensure that the correct hostname is supplied. Cause 11: ProtocolException: Could not get service ticket for principal name [caused by: com.dstc.security.kerberos.cryptoexception: Integrity check failure] The realm specified in idm.realm is case-sensitive and is usually uppercase. If the case does not match, the DES keys for the service will be incorrect, as they are derived from the fully-qualified principal name. Cause 12: Filter could not be loaded: com.dstc.security.util.licensing.invalidlicense: Error verifying license: Cannot open resource jcsi.licensing.cert.pem The licensing code can not find a license, either because it has not been installed, or Java 2 Security has been enabled, without a suitable policy file. 74

Maintenance and Troubleshooting Problem: Why is Internet Explorer trying to do NTLM? Cause: VSJ is designed to work with Windows Integrated Authentication using Kerberos. However, if your browser or Active Directory is not configured correctly this will fail, and Internet Explorer will attempt to fallback to NTLM authentication. If you have NTLM disabled in VSJ, or if you are using VSJ (WebLogic Edition), then you may be presented with a username/ password dialog, and you will see the following message in the error log: Could not authorize request: com.wedgetail.idm.sso.ntlmnegotiatedexception Generally, fallback to NTLM will occur for one of the following reasons: 1. You are using a Microsoft Windows 95, 98 or ME browser which does not support Kerberos. 2. You are not logged in to the domain. 3. You are trying to connect from a browser on the same host as that on which the application server is running. 4. The Service Principal Name (SPN) is not correctly mapped to the service account used by VSJ. 5. Internet Explorer is not configured properly. In particular, the site you are connecting to is not considered part of the Intranet Zone. You also need to ensure that Windows Integrated Authentication is enabled. One way to test whether it is cases 4 or 5 is to install a packet sniffer. We recommend Ethereal (http://www.ethereal.com). If case 4 has occurred, Ethereal should provide the following output: 1. HTTPresponse 401 Unauthorized 2. KRB_AP_REQ 3. KRB_AP_REP (Indicating a Kerberos Error) 4. HTTP request with the broken negotiate header. If you are certain that the SPN has been correctly set up, send the Ethereal trace to support@quest.com and one of our experienced support engineers will assist you in identifying the problem. If case 5 has occurred, no Kerberos traffic will be visible in the Ethereal trace. 75

Vintela Single Sign-on for Java from Quest Software Keytabs Problem: When using a keytab I get "Could not verify PAC in auth data" Cause: When generating a keytab using ktpass the default key type is DES-CBC-CRC. There is a known problem using these types of keys. You must specify -crypto DES-CBC-MD5 when generating the keytab. Problem: I am getting a "No keytab entry for decrypting. Data encrypted with key type 23..." message. Cause: This error is caused when the keytab used contains only DES keys but the account is not set to 'Use DES only'. This can be fixed by either adding an RC4 key to the keytab, or setting the user account to Use DES only. Network Connections Problem: When attempting to connect to a URL protected by the filter you receive an error message: 403 Forbidden This Connection Must be secured. Cause: By default, VSJ requires that communications be performed securely (for example using HTTPS). This is for two reasons: Once a session is authenticated, the filter does not require authentication for subsequent requests using the same session ID. If it were, this would require an extra round-trip (or in some cases, two) to authenticate each request. However, this means an attacker who is able to sniff the session ID would be able to hijack an authenticated session. Note: even if every request was authenticated, the SPNEGO protocol does not tie any of the content in the HTTP request to the authentication information, so an active attacker could still hijack session requests. If the fallback mechanism is supported for non-internet Explorer browsers, Kerberos usernames and passwords will be sent unprotected over the network. We strongly recommend using SSL to secure communications for these reasons. However, should you wish to use the SSO solution to authenticate clients over unprotected connections (for example, for testing, or where there is a very low risk of attackers hijacking sessions), then you may set the idm.allowunsecured option to true. 76

Maintenance and Troubleshooting Credential Delegation Problem: Servlet authenticates but there are no delegated credentials (or deleg example displays message "Expected delegated credential but didn't get any") Cause: The service account is probably not trusted for delegation See Step 1: Create a User Account. Cause 13: The user may have their account configured so that delegation is not allowed. Check the user's account properties in Active Directory. Problem: Delegation to IIS fails, with a MIC check problem. Cause: This is because IIS seems to send back a clone of the mechtoken in the MIC field, which causes MIC-checking to fail. Setting the system property idm.spnego.nomiccheck to true will disable MIC checking. Debugging Problem: How do I get more debug information out of VSJ? At the lowest level setting the Java system properties jcsi.kerberos.debug to the value true and idm.spnego.debug to the value true should produce logging to the standard error output stream. VSJ Servlet Filter is configured on a per web application basis. This configuration is based upon log4j and defined in the Web applications web.xml deployment descriptor. VSJ WebLogic Edition is configured through the WLS administration console by creating and adding the Default Audit Provider in the Realms -> Providers -> Auditing menu. VSJ WebSphere Edition logging is configured through the WAS administration through the Troubleshooting -> Logs and Trace -> servername -> Modify menu. VSJ JBoss Edition integrates with the Log4J logging framework used by JBoss. The Log4J configuration file can be found at ${jboss.home}/server/${jboss.server}/conf/log4j.xml. 77

Vintela Single Sign-on for Java from Quest Software 78

Appendix A VSJ Configuration Parameters Parameter Description idm.realm idm.princ idm.keytab idm.password idm.allowntlm The Active Directory domain to be used for authentication. The Kerberos service principal to use. This should be in the form HTTP/fully-qualified-host, for example, "HTTP/example.wedgetail.com". It defaults to "HTTP/localhost". The file containing the keytab that Kerberos will use for user-to-service authentication. If unspecified, VSJ will default to using an in-memory keytab with a password specified in the com.wedgetail.idm.sso.password custom property or the idm.password parameter. The password of the Kerberos service principal. VSJ will create an in-memory keytab using this password. NOTE: This parameter is required if the idm.keytab parameter or com.wedgetail.idm.sso.password property are not set. Specifies whether to allow fallback to NTLM authentication. This is required if you wish to use the SSO solution with pre-windows 2000/XP Internet Explorer browsers which do not support SPNEGO. The default is false. 79

Vintela Single Sign-on for Java from Quest Software Parameter idm.allowfallback idm.allowunsecured idm.userhandledexcept idm.kdc idm.fallbackcrossrealm idm.supportmultiplespn Description Specifies whether to allow fallback to basic authentication. This is required if you wish to use the SSO solution with non-internet Explorer browsers. The default is false. Specifies whether to allow authentication over an unsecured channel. It is strongly recommended that this option not be set to true unless there is a very low risk of an attacker accessing the communication channel between the client and server. The default, if not set, is false. Setting this parameter to true will propagate exceptions from VSJ code to the Web server so that you can write your own error pages based upon the VSJ error that occurs. The Active Directory KDC against which secondary credentials should be validated This can be used for basic fallback, or credential delegation. By default, the KDC will be discovered automatically and this parameter should only be used if automatic discovery fails, or if a different KDC to the one discovered automatically should be used. If this parameter is set, VSJ attempts to guess the client's realm from the domain part of the hostname returned by ServletRequest.getRemoteAddr(), and the user is not required to append the realm to their username. By default this is false. Specifies whether to support multiple service principal names. If this option is set to true, then the server will use the service name in the ticket to determine which key to use for decryption. The default is false. (See Creating Keytab Files.) 80

VSJ Configuration Parameters Parameter Description idm.ad.site idm.ad.login idm.ad.security idm.access.policy idm.access.groupsasroles idm.ad.userprincipalattribute The Active Directory site in which this server should be placed. The username used to access Active Directory user information via simple authentication. If specified it should be the fully-qualified user created for the service principal as described in Step 1: Create a User Account (for example, user@example.com). This parameter specifies how connections to LDAP servers are secured. Possible options are sasl and simple. Specifies the file from which access policies for authorization will be read. If unspecified, access must be handled programmatically. If a given role is not associated with any users, it treats the role as an Active Directory group. By default this is false. This parameter can be set to the name of an Active Directory attribute. If set, the value of this attribute will be made available to web applications rather than the user name that was authenticated. This could be used to allow a user to login normally with username and password but then be known to the web application by perhaps an employee id, which is stored and managed in Active Directory. This property takes precendence over idm.ad.qualifyuserprincipal but is preceded by idm.ad.userprincipalformatterclass. 81

Vintela Single Sign-on for Java from Quest Software Parameter com.wedgetail.idm.sso.password jcsi.kerberos.nameservers idm.ad.qualifyuserprincipal idm.ad.userprincipalformatterclass Description The password of the Kerberos service principal. VSJ will create an in-memory keytab using this password. Note: This property is required if idm.keytab or idm.password parameters are not set. This is a system property. Configure this property in the Custom Properties in the Java Virtual Machine section. See Keytabs and Passwords. A colon-separated list of one or more DNS servers that VSJ should use to look up DNS SRV records for Active Directory domain controllers. Specify each DNS server as either a hostname or as an IPv4 address. Normally VSJ automatically discovers DNS servers by querying the JVM and/or the operating system. However, in some circumstances (such as when VSJ is running on z/os), VSJ s auto-discovery logic comes up empty-handed and so the list of DNS servers must be specified explicitly. This is a system property. Configure this property in the Custom Properties in the Java Virtual Machine section. Fully qualify the authenticated user name returned by VSJ i.e. append the Active Directory domain name. The idm.ad.userprincipal attribute and idm.ad.userprincipalformatterclass properties take precedence over this one. This property should be set to true if you are using the VSJ User Registry in VSJ WebSphere Edition in an environment with multiple Active Directory domains. The default, if not set, is false. The class name of a UserPrincipalFormatter implementation to use for formatting principal names returned by VSJ. This property takes precendence over both idm.ad.userprincipalattribute and idm.ad.qualifyuserprincipal. 82

VSJ Configuration Parameters Parameter idm.ntlm.signing.username idm.ntlm.signing.domain idm.ntlm.signing.password idm.ntlm.signing.always idm.trimunsolicitedbasic Description The NTLM logon name of a user account that VSJ can use for NTLM signing. The NTLM domain (not the AD domain) to which the above user account belongs. The password for the above account. See Keytabs and Passwords in Security Issues. True means that VSJ should always use these signing parameters. False means that VSJ should only use these signing parameters if it got an exception while trying to authenticate a user without using these signing parameters. The default value is recommended. Optimize unnecessary HTTP Basic reauthentication. This is an optional boolean tuning parameter; the default is false. If this is true and a client sends us an "Authorization: Basic" header when we don't need it (because we have already authenticated the client) then we ignore the header. If this is false then we process the header (and reauthenticate the client) even though we don't really need to. This parameter is never harmful but only helps performance in the unusual case where a client sends Basic authentication much more often than necessary (e.g. on every request). 83

Vintela Single Sign-on for Java from Quest Software Parameter idm.trimunsolicitedntlm Description Optimize unnecessary HTTP NTLM reauthentication. This is an optional boolean tuning parameter; the default is false. If this is true and a client sends us an "Authorization: NTLM" header (or NTLM dressed up as Negotiate) when we don't need it (because we have already authenticated the client) then we process it just enough to humour the client (because otherwise Internet Explorer won't send us the body of a POST or PUT request) but we don't bother to perform the last, rather expensive, step of NTLM authentication (contacting a domain controller to validate the NTLM password hashes). If this is false then we process the header completely (and reauthenticate the client) even though w we don't really need to. It is generally a good idea to enable this option if idm.allowntlm is enabled and a significant percentage of your HTTP NTLM requests are POST or PUT (because Internet Explorer reauthenticates on every HTTP request with a content-body, such as POST or PUT). There are no known disadvantages to enabling this option. 84

VSJ Configuration Parameters Parameter idm.trimunsolicitedspnego idm.ntlm.usercache.max Size idm.ntlm.usercache.max Age Description Optimize unnecessary HTTP SPNEGO reauthentication. This is an optional boolean tuning parameter; the default is false. If this is true and a client sends us an SPNEGO token (in an "Authorization: Negotiate" header) when we don't need it (because we have already authenticated the client) then we ignore the header. If this is false then we process the header (and reauthenticate the client) even though we don't really need to. This option is only necessary if a significant percentage of your HTTP SPNEGO requests are POST or PUT (because Internet Explorer reauthenticates on every HTTP request with a content-body, such as POST or PUT) and the CPU overhead of the unnecessary SPNEGO/Kerberos reauthentication operations is becoming prohibitive. Note: if this option is enabled, VSJ does not send an SPNEGO response token ("NegTokenTarg"). This is fine for Internet Explorer, but may or may not be fine for other clients. The maximum number of entries in the NTLM user cache. The maximum lifetime (in milliseconds) of entries in the NTLM user cache. This value only needs to be large enough so that repeated authentications for the same NTLM user over a short period (e.g. by HTTP clients that don't support JSESSIONID cookies) will use the cache (instead of triggering repeated expensive lookups for the same information), so the default is ten minutes (600000 millisec). 85

Vintela Single Sign-on for Java from Quest Software 86

Glossary Active Directory A hierarchical directory service that comes with Windows 2000. It is LDAP compliant and built on the Internet's Domain Naming System (DNS). Active Directory can function in a heterogeneous, enterprise network and encompass other directories including NDS and NIS+. access control authentication authorization A set of procedures performed by hardware, software and administrators to monitor access, identify users requesting access, record access attempts, and grant or deny access. Compare with authorization. Authentication is the process of determining whether someone or something is, in fact, who or what it is declared to be. In private and public computer networks (including the Internet), authentication is commonly done through the use of logon passwords. Knowledge of the password is assumed to guarantee that the user is authentic. Each user registers initially (or is registered by someone else), using an assigned or self-declared password. On each subsequent use, the user must know and use the previously declared password. The weakness in this system for transactions that are significant (such as the exchange of money) is that passwords can often be stolen, accidentally revealed, or forgotten. Logically, authentication precedes authorization (although they may often seem to be combined). Authorization is the process of giving someone permission to do or have something. In multi-user computer systems, a system administrator defines for the system which users are allowed access to the system and what privileges of use (such as access to which file directories, hours of access, amount of allocated storage space, and so forth). Assuming that someone has logged in to a computer operating system or application, the system or application may want to identify what resources the user can be given during this session. 87

Vintela Single Sign-on for Java from Quest Software Thus, authorization is sometimes seen as both the preliminary setting up of permissions by a system administrator and the actual checking of the permission values that have been set up when a user is getting access. Logically, authorization is preceded by authentication. DeMilitarized Zone (DMZ) A middle ground between an organization's trusted internal network and an untrusted, external network such as the Internet. Enterprise JavaBeans (EJB) A software component in Sun's Java EE platform, which provides a pure Java environment for developing and running distributed applications. EJBs inherently provide future scalability and also allow multiple user interfaces to be used. Generic Security Service API (GSS-API) A C API for distributed security services. Described in IETF RFC 2743. Java Authentication and Authorization Service (JAAS) A package that enables services to authenticate and enforce access controls upon users. It implements a Java version of the standard Pluggable Authentication Module (PAM) framework, and supports user-based authorization. Java Cryptography Architecture (JCA) An umbrella term from Sun for implementing security functions for the Java platform. It includes Sun's Java Security API as well as the Java Cryptography Extension (JCE), which adds more programming interfaces for encryption and key exchange. It also provides a mechanism for adding third-party security packages such as algorithms and digital signatures into Java applications. Java DataBase Connectivity (JDBC) A programming interface that lets Java applications access a database via the SQL language. Since Java interpreters (Java Virtual Machines) are available for all major client platforms, this allows a platform-independent database application to be written. Kerberized application A software application that requires or performs Kerberos authentication. 88

Glossary Kerberos Kerberos is a secure method for authenticating a request for a service in a computer network. Kerberos was developed in the Athena Project at the Massachusetts Institute of Technology (MIT). The name is taken from Greek mythology; Kerberos was a three-headed dog who guarded the gates of Hades. Kerberos lets a user request an encrypted ticket from an authentication process that can then be used to request a particular service from a server. The user's password does not have to pass through the network. Lightweight Directory Access Protocol (LDAP) A software protocol for enabling anyone to locate organizations, individuals, and other resources such as files and devices in a network, whether on the public Internet or on a corporate intranet. LDAP is a lightweight version of Directory Access Protocol (DAP), which is part of X.500, a standard for directory services in a network. Netscape includes it in its latest Communicator suite of products. Microsoft includes it as part of what it calls Active Directory in a number of products including Outlook Express. Novell's NetWare Directory Services interoperates with LDAP. Cisco also supports it in its networking products. Secure Sockets Layer (SSL) The Secure Sockets Layer (SSL) is a commonly-used protocol for managing the security of message transmission on the Internet. SSL uses a program layer located between the Internet's Hypertext Transfer Protocol (HTTP) and Transport Control Protocol (TCP) layers. SSL is included as part of both the Microsoft and Netscape browsers and most Web server products. Developed by Netscape, SSL also gained the support of Microsoft and other Internet client/server developers, becoming the de facto standard until evolving into Transport Layer Security (TLS). The sockets part of the term refers to the sockets method of passing data back and forth between a client and a server program in a network or between program layers in the same computer. SSL uses the public/private key encryption system from RSA, which also includes the use of a digital certificate. 89

Vintela Single Sign-on for Java from Quest Software Simple and Protected GSS-API Negotiation Mechanism (SPNEGO) A GSSAPI mechanism that allows the secure negotiation of the mechanism to be used by two different GSSAPI implementations. In essence, SPNEGO defines a universal but separate mechanism, solely for the purpose of negotiating the use of other security mechanisms. SPNEGO itself does not define or provide authentication or data protection, although it can allow negotiators to determine if the negotiation has been subverted, once a mechanism is established. Single Sign-On (SSO) An authentication process in a client/server relationship where the user, or client, can enter one name and password and have access to more than one application or access to a number of resources within an enterprise. Single sign-on removes the need for the user to enter further authentications when switching between applications. 90

INDEX A Active Directory about 5 10 groups 2, 6??, 8,?? 8 logon process 8 scopes 7 types 7 VSJ 8 installation 16 LDAP integration 6 permissions 57 Public Key Infrastructure (PKI) support 6 sites 2, 9??, 9,?? 9, 27 smartcard support 6 VSJ 10 Windows native credential cache 6 authentication 2, 40, 42, 55, 56, 62, 64, 76, 79, 87 basic 18, 42, 55, 73, 80 Kerberos 55 NTLM 17, 63, 75, 79 PKI 6 simple 81 smartcard 6 user 19 Windows-integrated 16, 17, 18, 25, 26, 27, 55, 56, 62, 71, 72, 75 B basic fallback 18, 42, 54, 55, 56, 59, 62, 80 C client machine 16 browser 17 cookies 54, 55 credential cache, native Microsoft Windows 6 credential delegation 32, 39, 41, 80 D Denial of Service attack 54, 60 deployment descriptor 70, 73 deployment risks 18, 19 replication interruptions 19 resource security 19 service unavailability 18 time sychronization 18 Domain Name Service (DNS) 14, 15 G groups, Active Directory 6 8 I installation Active Directory 16 application server 16 client machine 16 Internet Explorer and SPNEGO 11 J jkinit 50 jklist 50 JKTools 50 examples 51 jkinit 50 jklist 50 jktutil 51 K Kerberos 3, 5 authentication 3, 4, 5, 55 LDAP integration 6 MIT 3, 4, 6, 41, 89 Privilege Attribute Certificates (PAC) 6 L LDAP vii, 5, 6, 8, 61, 81, 87, 89 Active Directory integration 6 Kerberos integration 6 logging 38, 68 91

Vintela Single Sign-on for Java from Quest Software M maintenance 68, 69 account settings 68 logging 68 network policy changes 69 new users/groups 68 Microsoft Windows credential cache, native 6 integrated authentication 16, 17, 18, 25, 26, 27, 55, 56, 62, 71, 72, 75 MIT Kerberos 3, 4, 6, 41, 89 N NTLM 63, 64, 75 authentication 17, 63, 75, 79 versions 64 P PAC, see Privilege Attribute Certificate (PAC) permissions, Active Directory 57 PKI, see Public Key Infrastructure (PKI) Privilege Attribute Certificate (PAC) 6, 8, 61, 76 Public Key Infrastructure (PKI) Active Directory, support in 6 R RC4 76 S SASL 61 sites, Active Directory 9 smartcard Active Directory, support in 6 SPNEGO 2, 40, 41, 42, 55, 56, 63, 71, 76, 79, 90 and Internet Explorer 11 T Time synchronization service 15 troubleshooting authentication 71, 72 AuthFilter 73 blank page, Internet Explorer 6 72 ConfigException 70, 73 credential delegation 77 CryptoException 69 debug information 77 DNS error 72 error 401 71 error 403 71, 76 error 500 69, 71 IIS delegation 77 integrity check failure 71 InvalidLicense 74 keytab 76 MIC-checking 77 no keytab entry 76 NTLM 75 ProtocolException 74 SecurityException 72 Servlet Error 70 ServletException 73 V VSJ about 2 Active Directory groups 8 Active Directory, and 10 deployment risks 18, 19 how it works 11 installation requirements 14, 15, 16 logging 38 maintenance 68, 69 92