OpenAM

Download from Wow! eBook

OpenAM

Written and tested with OpenAM Snapshot 9—the Single Sign-On (SSO) tool for securing your web applications in a fast and easy way

Indira Thangasamy

BIRMINGHAM - MUMBAI

OpenAM Copyright © 2011 Packt Publishing

All rights reserved. No part of this book may be reproduced, stored in a retrieval system, or transmitted in any form or by any means, without the prior written permission of the publisher, except in the case of brief quotations embedded in critical articles or reviews. Every effort has been made in the preparation of this book to ensure the accuracy of the information presented. However, the information contained in this book is sold without warranty, either express or implied. Neither the author(s), nor Packt Publishing, and its dealers and distributors will be held liable for any damages caused or alleged to be caused directly or indirectly by this book. Packt Publishing has endeavored to provide trademark information about all of the companies and products mentioned in this book by the appropriate use of capitals. However, Packt Publishing cannot guarantee the accuracy of this information.

First published: January 2011

Production Reference: 1190111

Published by Packt Publishing Ltd. 32 Lincoln Road Olton Birmingham, B27 6PA, UK. ISBN 978-1-849510-22-6 www.packtpub.com

Cover Image by Asher Wishkerman ([email protected] )

Credits Author Indira Thangasamy Reviewers Xuekun Kou Peter Major Acquisition Editor Usha Iyer Development Editor Tarun Singh Technical Editors Kavita Iyer Krutika Katelia Harshit Shah Copy Editor Neha Shetty Indexer Tejal Daruwale

Editorial Team Leader Akshara Aware Project Team Leader Ashwin Shetty Project Coordinator Poorvi Nair Zainab Bagasrawala Proofreader Joanna McMahon Graphics Nilesh Mohite Production Coordinator Arvindkumar Gupta Cover Work Arvindkumar Gupta Alwin Roy Shantanu Zagade Kruthika Bangera

About the Author Indirajith ("Indira") Thangasamy was born in Melanedumbur, a remote place

in the southern part of India, and now resides in the San Francisco bay area with his wife Ramya and kids, Kavin and Iniya. After graduating with a Master of Technology in computer science, Indira started as an embedded systems developer at Robert Bosch GmbH in the Schengen area in India. In the late 90's, he relocated to the USA. During this period, he developed security applications to augment the Wells Fargo bank's security infrastructure. This job introduced a lot of security technology that helped him to develop an interest in the security arena. Inspired by the innovations of Sun Microsystems Inc., specifically RPC/NFS (not Java at that time), he wanted to work for Sun at some point in his career. He eventually started at Sun as a consultant to develop the tests for Solaris kernel libraries. Later, he worked as an employee for almost a decade in various capacities at Sun Microsystems Inc. Now, as part of the Oracle Corporation, Indira is serving as a Senior Manager in software development, managing the Fusion middleware access management quality engineering organization. His expertise and interests includes the quality engineering process, automation, LDAP, webservices, System Administration, networking, IAM, and Security. Indira has been associated with the OpenSSO product since its inception and is instrumental in delivering a high quality product to its customers. If not working, he is playing with his kids besides growing grapes in his garden. Indira teaches the Tamil language to the kids at California Tamil Academy—a nonprofit organization. Indira blogs about technologies and OpenSSO on his blogs http://blogs.sun.com/indira/ and http://indirat.wordpress.com.

Acknowledgement First and foremost, I would like to thank and dedicate all my success to my maternal grandmother, Alamelu Ammal. Without her love and support my existence would not have been possible. I did not realize her value when she was alive. I would like to thank and acknowledge the team that created a great product called OpenSSO. If you find this book useful, then the credit goes to this team. I take the responsibility for any omissions or errors that may have occurred inadvertently. My sincere gratitude to Jamie Nelson, the then Director of Engineering, for allowing and encouraging me to work on this book, followed by Mike Hwa, Director of Quality, Yaqing Wang, VP of Quality, and Oracle Senior Management for permitting me to pursue this book. I would like to thank all my current and erstwhile colleagues who I have worked with over the years. I learned something new from each one of you, and for that I am very grateful. I owe many thanks and appreciation to my official reviewers, Peter Major and Xuekun Kou, for their valuable comments. I cannot thank the Packt crew enough, starting with Priya Mukherji, Usha Iyer, Zainab Bagasrawala, Poorvi Nair, Tarun Singh, and Technical Editors Kavita Iyer and Harshit Shah for their support and patience throughout the process. Here goes my next set of acknowledgements which is of paramount importance. My parents Thangasamy and Hamsayal—I know how hard you worked to raise us, thank you for your selfless love and affection. My brothers, sisters-in-law, sister Alli, brother-in-law Devaraju, and my extended family folks back in India. I owe my thanks to my in-laws, Kalimuthu, Revathy, sister-in-law Suba, and family. I am blessed to have such a close-knit family.

To my wife, if at all I am successful in life, it is not through sheer luck or brilliance, it is all because of my loving wife Ramya's support and endless love. She takes care of me like a child, starting with what I eat, what I wear, and so on and so forth. Ramya did help me write some scripts to test the samples in the book, and also provided comments about the draft from the reader's perspective. Whether I was working on the book or not, she always took care of the kids, their extracurricular activities amidst her own busy work schedule. Thanks Ramya, I am very fortunate to have you in my life. To my kids Kavin chellam and Iniya kutti—they are the source of my energy and happiness. I know Kavin, I missed your soccer games, I also heard you saying 'Appa is glued to the computer'. I am sorry kids I could not play with you as much as we all wanted, and promise to make it up to you. I could not conclude without thanking my friends (you know who you are) who invariably asked about my book and the deadlines. They checked on me more than my publishers. Thank you folks! Hopefully, I have not forgotten anyone but if I have, it an oversight.

About the Reviewers Xuekun Kou has extensive experience with Enterprise Java system architecture. He

has designed, implemented, and deployed Java EE-based solutions for all the leading Java EE application server platforms. His experience with OpenSSO dates back to its very beginning: Sun Microsystems' Directory Server Access Management Edition (DSAME). Xuekun Kou is the author of the book, GlassFish Administration, published by Packt Publishing. He holds degrees from the Florida State University and the University of Science and Technology of China. I want to thank my wife, Jianghua, for being so patient with me and spending many nights reviewing the draft. Without her understanding and encouragement, it would have been much harder to complete the review on time. I appreciate the opportunity Packt Publishing gave me to review the book, and I appreciate Indira's timely response to my review comments.

Peter Major—at the time of this writing—is a senior student at the Budapest University of Technology and Economics studying Computer Engineering. He first started using OpenSSO in 2009 in his dormitory to manage the students accounts, and since January 2010 he has developed several commercially used authentication modules. Since April 2010, he's been an active member of the OpenSSO community and also a contributor at ForgeRock OpenAM. I'd like to thank my fellow colleague, Adam Lantos, who helped me in the unknown areas while reviewing the book.

www.PacktPub.com Support files, eBooks, discount offers and more

You might want to visit www.PacktPub.com for support files and downloads related to your book. Did you know that Packt offers eBook versions of every book published, with PDF and ePub files available? You can upgrade to the eBook version at www.PacktPub. com and as a print book customer, you are entitled to a discount on the eBook copy. Get in touch with us at [email protected] for more details. At www.PacktPub.com, you can also read a collection of free technical articles, sign up for a range of free newsletters and receive exclusive discounts and offers on Packt books and eBooks.

http://PacktLib.PacktPub.com

Do you need instant solutions to your IT questions? PacktLib is Packt's online digital book library. Here, you can access, read and search across Packt's entire library of books. 

Why Subscribe? •

Fully searchable across every book published by Packt

•

Copy and paste, print, and bookmark content

•

On demand and accessible via web browser

Free Access for Packt account holders

If you have an account with Packt at www.PacktPub.com, you can use this to access PacktLib today and view nine entirely free books. Simply use your login credentials for immediate access.

Download from Wow! eBook

Table of Contents Preface 1 Chapter 1: Getting Started 7 History of OpenSSO OpenSSO vs. OpenAM OpenSSO—an overview OpenSSO services

Federation services Web Services Security and Secure Token Service OpenSSO Entitlements Service

What kind of problems does OpenSSO solve?

9 10 11 11 12 13 15

16

Access management 16 Federation 16 Securing web services 17 Entitlements 18

Summary 19

Chapter 2: OpenSSO Deployment and Configuration

Deployment requirements for OpenSSO web application Containers and operating systems support Java SDK support Disk and memory requirements Browser requirements Configuration store versus Identity Store Configuration store Embedded configuration store External Sun Directory Server Enterprise Edition configuration store

Identity store How to obtain OpenSSO Building OpenSSO from source Downloading OpenSSO binary

21 22 22 23 23 24 24 24

25 26

27 28 28 29

Table of Contents

Configuring OpenSSO Installing and configuring Apache Tomcat 6.0.20 OpenSSO one click configuration Verifying OpenSSO configuration What just happened? OpenSSO–configuration choices Single server configuration–using embedded configuration store

31 34 37 38 39 40

Single server configuration–using external configuration store Multi-server configuration–embedded configuration store

47 50

Layout of the configuration directory

Prerequisites for multi-server configuration Adding OpenSSO to an existing deployment Verification of multi-server deployment

31

46

51 52 55

Configuring using command line configurator 56 Configuring OpenSSO with SSL/TLS 58 Configuring command line tools 58 Uninstalling OpenSSO 61 OpenSSO release and support model 61 Summary 62

Chapter 3: Administrating OpenSSO Administration interfaces Accessing the administrative console Console views and privileges Console landing page–common tasks Access control tab

63 64 65 66 69 70

General 71 Authentication 71 Service 72 Data stores 73 Privileges 74 Policies 77 Subjects 79 Agents 81

Configuration

83

Sessions tab

85

Retrieving all the server properties Updating server configuration properties Removing properties from server configuration Managing sessions using ssoadm

Customizing the console Extending LDAP schema Customizing OpenSSO User Service Adding attributes to amUser.xml

[ ii ]

84 84 85 86

86 87 88

88

Table of Contents Removing User Service schema Adding the updated User Service schema Adding the labels Adding the custom attributes to data store configurations Updating privileges Testing the changes

Summary

Chapter 4: Authentication and Session Service Authentication process Cookies in OpenSSO Authentication types and URL parameters

89 90 90 91 92 93

94

95 96 97 98

Module 99 Level 100 Service 100 User 101 Role 101 Realm 101 Resource 102

Other authentication URL parameters IDToken parameter goto and gotoOnFail parameters locale parameter arg parameter iPSPCookie parameter ForceAuth parameter PersistAMCookie parameter

Authentication modules, instances, and chains LDAP authentication Creating an authentication instance Updating an authentication instance Reading an authentication instance Using an authentication instance Deleting an authentication instance

Authentication chains

103

103 103 104 105 106 106 107

107 108

108 109 109 110 110

111

Creating an authentication chain Updating an authentication chain Reading an authentication chain Using an authentication chain Performing a user-based authentication Deleting an authentication chain

112 112 113 113 113 114

Authentication modules 114 LDAP 115 Active Directory 115 Data store 115 Anonymous 116 Certificate (X.509) 116 [ iii ]

Table of Contents

Configuring Tomcat in SSL using CA signed certificate 117 HTTP basic authentication 120 Membership 120 JDBC 120 HOTP 121 SecurID 122 SafeWord 122 RADIUS 122 Unix 123 Windows NT 123 Windows Desktop SSO 124 Core 124 User profile requirement Setting user profile attributes in an SSO token

Adding custom authentication modules Session Service Session Service schema Updating Session Service

Session life cycle

124 126

128 129 130

130

131

Session structuring Session state transition Session properties Session change notification and polling Session persistence and constraints

131 132 133 134 135

Summary

Chapter 5: Password Reset and Account Management

136

137

Account lockout 138 Configuring account lockout 138 Physical lockout 140 In-memory lockout 141 Applying a password reset 142 Prerequisites 142 Configuring the password reset service in OpenSSO 143 Assigning service and update service attributes Creating and assigning OpenDS password policy

143 149

Summary

153

OpenSSO Policy Framework Protecting a sample application on Tomcat

156 158

Chapter 6: Protecting a Simple Web Application to Provide SSO 155 Creating the agent profile Installing and configuring the agents

[ iv ]

159 160

Table of Contents Deploying and configuring the Java application Creating policies and associated identities Testing the SSO Fetching user profile attributes

160 161 164 167

Summary 168

Chapter 7: Integrating Salesforce and Google Apps

169

Chapter 8: Identity Stores

185

Integrating OpenSSO with Salesforce applications Configuring hosted identity provider and circle of trust Configuring OpenSSO metadata for Salesforce.com Configuring users for Salesforce.com Verifying the SSO Integrating with Google Apps Configuring the hosted identity provider Configuring SSO parameters at Google Apps Configuring users for Google Apps Verifying SSO Summary Identity store types Caching and notification Persistent search-based notification Time-to-live based notification TTL-specific properties for Identity Repository cache Supported identity stores User schema Access Manager Repository plugin Creating an Access Manager Repository plugin data store Displaying the data store properties Updating data store properties Deleting data stores Removing the Access Manager Repository plugin

170 171 172 174 176 177 178 179 180 181 183 186 188 189 191 191 192 192 193

194 195 196 196 196

Oracle Directory Server Enterprise Edition

197

Data store for OpenDS Data store for Tivoli DS Data store for Active Directory Data store for Active Directory Application Mode Datastore for OpenLDAP Configuring an OpenLDAP suffix

198 199 199 199 200 200

Creating a data store for Oracle DSEE Updating the data store Deleting the data store

[v]

197 198 198

Table of Contents

Extending the schema Preparing the suffix with necessary entries Creating an OpenLDAP data store Testing the data store Multiple data stores Summary

Chapter 9: RESTful Identity Services

201 202 203 203 204 205

207

Prerequisites 208 Invoking REST interfaces 210 Authentication 210 Authenticating with URL parameters 211 Validating an SSO token 212 Invalidating session (logout) 213 Creating log events 213 Authorization 214 Identity CRUD operations 215 Searching identities 215 Searching for user identities Searching groups Searching for agents

216 216 216

Retrieving identity attributes Creating agent identities Creating user identities Creating group identities Updating identities Deleting identities

217 218 219 219 220 221

Deleting user identities Deleting group identities Deleting the agent identities

221 221 221

Other REST interfaces 222 Summary 222

Chapter 10: Backup, Recovery, and Logging Backing up configuration data Backing up the OpenSSO configuration files Backing up the OpenSSO configuration data Crash recovery and restore Test to production Performing the configuration change Configuring the export test server Configuring OpenSSO on the production server Adapting the test configuration data Importing into the production system [ vi ]

223 224 225 226 227 228 229

229 230 231 232

Table of Contents

OpenSSO audit and logging

232

File-based logging Database logging

236 237

Enabling debug (trace) level logging Audit logging

233 234

Remote logging Secure logging

240 240

Summary

Chapter 11: Troubleshooting and Diagnostics OpenSSO diagnostic tools Installing and configuring the tool Invoking the tool Troubleshooting Installation and configuration Scenario 1 Scenario 2 Scenario 3 Scenario 4

243

245 245 246 246 248 249

249 250 250 251

Authentication and session areas

252

Identity repository and password reset

253

Policy and agents

255

Command line tools

257

Scenario 1 Scenario 2 Scenario 3 Scenario 4 Scenario 1 Scenario 2 Scenario 3 Scenario 4 Scenario 5 Scenario 1 Scenario 2 Scenario 3

252 252 252 253 253 254 254 255 255 255 256 257

Scenario 1 Scenario 2

257 258

Summary 259

Index 261

[ vii ]

Preface OpenAM is an open source continuation of the OpenSSO project that was taken over, and later scrapped, by Oracle. OpenAM is the only commercial-grade, featurerich web application that provides SSO solutions. It has a variety of features and a powerful Single Sign-On (SSO) capability, but the implementation can be tricky, and the unorganized and incoherent online documentation is not very helpful. The OpenAM book will serve as a guide to everything you need to know to get started with implementing Single Sign-On using OpenAM to protect your web applications, along with real-world examples. The author's extensive experience in testing and troubleshooting OpenAM enables him to share insights on how the product works, its strengths, its weaknesses, and some inside information. If you are reading this, you probably want to protect your web application using OpenAM. The book starts off with an introduction to OpenAM and describes the core features and the kinds of problems that can be solved by OpenAM. Then it provides you with detailed instructions on how to protect your web applications by using the OpenAM server and policy agents. You will also learn about the user interface elements in order to manage OpenAM successfully. You'll understand the concepts of identity web services provided by OpenAM. There are examples in the book that describe how the REST-based identity services can be invoked and utilized. In the final chapters, you will find detailed discussions about backup, recovery, and audit logging. The book concludes by discussing some of the common OpenAM problems and tips to troubleshoot them. Although the project name has changed from OpenSSO to OpenAM, the product screen and file names still reflect OpenSSO. Hence, you will encounter the term "OpenSSO" throughout the book. This practical, hands-on guide will teach you how to protect your web applications by implementing Single Sign-On using OpenAM.

Preface

What this book covers

Chapter 1, Getting Started, covers the history of OpenSSO that dates back to early 2000 when Sun Microsystems started this as a Directory Server Access Management Edition (DSAME). It underwent multiple identity changes before fixing on OpenSSO. Chapter 2, OpenSSO Deployment and Configuration, teaches the basic environmental requirements for deploying the OpenSSO web application. OpenSSO provides both browser-based configurators for the web comfortable users and command line-based interfaces for the system administrators who are fond of doing things the command line way. Chapter 3, Administrating OpenSSO, introduces to OpenSSO administration interfaces: a browser-based administrative console, and a command line interface called ssoadm. Chapter 4, Authentication and Session Service, teaches at length about various authentication mechanisms supported by the OpenSSO server. It also teaches a lot about the session service, and SSO token structure and properties. Session high availability and constraints are one of the critical features to implement production level SSO deployments. Chapter 5, Password Reset and Account Management, explains that OpenSSO provides a decent level of identity provisioning and management features. To circumvent the denial of service type attacks, OpenSSO employs various lockout mechanisms—a permanent and temporary lockout which customers could deploy in their specific environments. Another salient feature that is embedded as part of the OpenSSO server application is the password reset application. Chapter 6, Protecting a Simple Web Application to Provide SSO, covers the basic principles of protecting a web application and providing a single login for multiple resources. Chapter 7, Integrating Salesforce and Google Apps, covers extensively the idea behind the SaaS-based applications and how those applications can be integrated with the OpenSSO identity provider environment. It specifically discusses the detailed procedures for integrating the Salesforce.com applications and hosted Google Apps. Chapter 8, Identity Stores, shows how OpenSSO is designed to support the commercially available LDAP servers. It also shows the caching and notificationrelated properties that form the key to achieving the optimal performance of the overall system. Chapter 9, RESTful Identity Services, covers most of the supported REST interfaces of OpenSSO identity web services. It provides decent support for the operations that are typically consumed by the client-side programs. [2]

Preface

Chapter 10, Backup, Recovery, and Logging, explains how it is critical to safeguard the configuration data to reconstruct the system from unexpected system crashes. It is also good practice to periodically backup the system for archival and audit purposes. Chapter 11, Troubleshooting and Diagnostics, discusses how one can troubleshoot the configuration and deployment problems by using the OpenSSO diagnostic tools. This tool provides a means to identify and isolate the static configuration and deployment issues. Without this tool, identifying the root cause of the problems could be cumbersome.

What you need for this book

It is assumed that the reader has access to one of the supported Operating Systems by OpenSSO, for example Redhat Linux 4. You'll also need: •

Apache Tomcat server 6.0.18+

•

OpenSSO/OpenAM build 9 binary opensso.zip either built from the express build 9 branch or downloaded from http://forgerock.com/downloads. html

•

OpenSSO Policy Agents 3.0 for Apache Tomcat from http://forgerock. com/downloads.html

•

OpenDS 2.2 downloaded from http://www.opends.org/

•

Java SDK 1.6 from http://www.oracle.com/technetwork/java/index.html

•

There are other software that may be required to try out the exercises in this book, such as MySQL for audit logging, OpenLDAP for user store, and Google Apps/Salesforce accounts for the SaaS-based SSO with OpenSSO

Who this book is for

If you are a security architect or a solution developer responsible for the design and development of web-based enterprise applications that need to provide authentication, authorization, and audit facilities along with SSO capabilities, then this book is for you. You do not require any prior knowledge of OpenAM to read this book. Familiarity with Java would be helpful, but is not essential.

Conventions

In this book, you will find a number of styles of text that distinguish between different kinds of information. Here are some examples of these styles, and an explanation of their meaning. [3]

Preface

Code words in text are shown as follows: "Verify that the output of the sha1sum returns the same value as of the check sum file downloaded from the OpenSSO site." A block of code is set as follows: " # OpenSSO Users Policy, Password Policies, config " dn: cn=OpenSSO Users Policy,cn=Password Policies,cn=config? " objectClass: ds-cfg-password-policy?

When we wish to draw your attention to a particular part of a code block, the relevant lines or items are set in bold:

Any command line input or output is written as follows: cvs -d :pserver:memberName @cvs.dev.java.net:/cvs checkout opensso

New terms and important words are shown in bold. Words that you see on the screen, in menus or dialog boxes for example, appear in the text like this: "However, the next option Custom Configuration is meant for advanced deployment.". Warnings or important notes appear in a box like this.

Tips and tricks appear like this.

Reader feedback

Feedback from our readers is always welcome. Let us know what you think about this book—what you liked or may have disliked. Reader feedback is important for us to develop titles that you really get the most out of. To send us general feedback, simply send an e-mail to [email protected], and mention the book title via the subject of your message.

[4]

Preface

If there is a book that you need and would like to see us publish, please send us a note in the SUGGEST A TITLE form on www.packtpub.com or e-mail [email protected]. If there is a topic that you have expertise in and you are interested in either writing or contributing to a book, see our author guide on www.packtpub.com/authors.

Customer support

Now that you are the proud owner of a Packt book, we have a number of things to help you to get the most from your purchase. Downloading the example code for this book You can download the example code files for all Packt books you have purchased from your account at http://www.PacktPub.com. If you purchased this book elsewhere, you can visit http://www.PacktPub. com/support and register to have the files e-mailed directly to you.

Errata

Although we have taken every care to ensure the accuracy of our content, mistakes do happen. If you find a mistake in one of our books—maybe a mistake in the text or the code—we would be grateful if you would report this to us. By doing so, you can save other readers from frustration and help us improve subsequent versions of this book. If you find any errata, please report them by visiting http://www.packtpub. com/support, selecting your book, clicking on the errata submission form link, and entering the details of your errata. Once your errata are verified, your submission will be accepted and the errata will be uploaded on our website, or added to any list of existing errata, under the Errata section of that title. Any existing errata can be viewed by selecting your title from http://www.packtpub.com/support.

Piracy

Piracy of copyright material on the Internet is an ongoing problem across all media. At Packt, we take the protection of our copyright and licenses very seriously. If you come across any illegal copies of our works, in any form, on the Internet, please provide us with the location address or website name immediately so that we can pursue a remedy.

[5]

Please contact us at [email protected] with a link to the suspected pirated material. We appreciate your help in protecting our authors, and our ability to bring you valuable content.

Questions

You can contact us at [email protected] if you are having a problem with any aspect of the book, and we will do our best to address it.

Getting Started Today's identity and access management is not just essential to workplace efficiency—it's also a key factor in reducing Information Technology enterprise costs and delivering value beyond security and compliance services. This is how the market analysts perceive the Identity and Access Management (IAM) market segment today. Before going further on the IAM arena, let us see what Identity and Access Management is and why organizations should even bother about it. With the advent of information technology, businesses are gearing up to embrace the new technologies in the market to simplify their resource management tasks. Adoption of these technologies improves the productivity in addition to meeting the governmental agencies' compliance requirements. In the olden days it used to be fairly easy to know whom we were dealing with and what they represented; a handshake, a signature, a photograph in a passport, or an identity badge, all played a role in physical identification. In the modern world, where computers and technology play a key role, one needs the electronic equivalents of these, to know whom we are dealing with and what authority they possess. In an enterprise environment, there is a wealth of information pertaining to the employees, customers, and partners that needs to be stored and managed securely. It is essential to ascertain who can access what kind of information. An identity of an entity can be established by enforcing appropriate authentication systems. This will ensure that the information is accessible only to legally permitted people or entities such as computers, or other network devices such as mobile phones among others. Well, this will guarantee there is no anonymous access to the information available in the company.

Getting Started

However, once authenticated, what information is available to the authenticated identity? Everything, or only selected information that is stored in the corporate database? This is where the access management comes into play. The access management establishes the privileges for the authenticated identity on what kind of information they are authorized to access. For example, an engineering manager does not need to know the company's financial data. This kind of information authorization is provided by the access management systems. In essence, the identity management deals with identity provisioning and synchronization, along with some level of auditing capabilities, whereas as the access management deals with the authentication and authorization information for those entities and what they can do. Together it is called IAM. Implementing proper IAM solutions helps the corporates to manage their information security, and helps to improve business processes and information sharing. For instance, using the federation feature, a business can easily integrate with another partner without replicating any identity information to the partner site, or they can securely exchange attributes of identities without actually storing them at the partner site. It is very critical for businesses to control the access of information and track the accesses to establish accountability on the actions made by the identities on these information resources. This enables the organizations to go back and audit the events in case of any discrepancy or wrongdoing, to track down the culprit. There have been a lot of incidents in the past where people have stolen information which they were not authorized to access because of no or poor IAM implementation. One of the most notorious examples of the potential harm that can result without identity management is the February 2001 incident where the FBI arrested one of its own veteran counterintelligence agents, Robert Philip Hanssen. He gave more than 6,000 pages of documents containing classified information to Russia and the former Soviet Union. He downloaded most of it from the bureau's computers. Controlling access to certain files makes it more difficult for insiders such as Hanssen, or outside hackers, to steal sensitive information.. Please refer to the following website to know more about the role of IAM in the working of the government. http://www.nextgov.com/the_basics/tb_20080327_1273.php:

[8]

Chapter 1

In this chapter we'll discuss the following topics: •

History of OpenSSO

•

OpenSSO vs. OpenAM

•

OpenSSO—an overview

•

What kind of problems does OpenSSO solve?

History of OpenSSO

Back in early 2000, Sun Microsystems Inc. started the Directory Server Access Management Edition project to develop a product that would solve the web Single Sign-On (SSO) problems. The initial scope was to just provide authentication and authorization as part of the SSO using a proprietary protocol. Over the years it evolved to become a lightweight pure Java application providing a comprehensive set of security features to protect the enterprise resources. After undergoing a lot of changes in terms of product name, features, among other things, it ended up with OpenSSO. As part of Sun Microsystems software business strategy, they have open sourced most of their commercial enterprise software products including Sun Java Enterprise System (JES), Java SDK, and Communication suite of products. OpenSSO is the term coined by the Sun's access management product team as part of their strategy to open source Sun Java System Access Manager, Sun Java System SAML v2 Plugin for Federation Services, and Sun Java System Federation Manager. OpenSSO is an integrated product that includes the features of both Access and Federation manager products. The goal was to amalgamate the access, federation, and web services features. This goal was achieved when Sun released the OpenSSO Enterprise 8.0 that received strong market traction and analysts coverage. Sun's OpenSSO product made it to the leadership quadrant in 2008 in the Access Management category which was published by the Gartner Analyst group. As part of the open source initiative, a lot of code re-factoring and feature alignments occurred that changed the product's outlook. It removed all the native dependencies that were required to build and deploy earlier. OpenSSO became the pure Java web application that enabled the customers and open source community to take advantage of the automatic deployment by just dropping the web archive on any Java servlet container to deploy it. The build and check-in processes were highly simplified which attracted the open source community to contribute to the code and quality of the product.

[9]

Getting Started

OpenSSO had a very flexible release model wherein new features or bug fixes could easily be implemented in the customer environment by picking up the nightly, express, or enterprise build. You can find more information on these different builds in the next chapter. OpenSSO Enterprise 8.0 was a major release by Sun that was built from the open source branch. After this release, there were two other express releases. Those were very feature-rich and introduced Secure Token Service (STS) and OAuth functionality. Express build 9 was not released in the binary form by Oracle but the source code has been made available to the open source community. This book is largely based on the binary built from the express build 9 cvs branch. You can download the OpenAM express build, built using the express build 9 branch from the Forgerock site. As part of the acquisition of Sun Microsystems Inc. by Oracle Corporation that happened back in early 2010, the release and support models have been changed for OpenSSO. If you are interested in obtaining a support contract for the enterprise version of the product, you should call up the Oracle support team or the product management team. Oracle continues its support for the OpenSSO enterprise's existing customers. For the OpenSSO open source version (also known as OpenAM) you can approach the Forgerock team to obtain support.

OpenSSO vs. OpenAM

OpenSSO was the only open source product in the access management segment that had production level quality. Over eight thousands test cases were executed on twelve different Java servlet containers. OpenSSO is supported by a vibrant community that includes engineers, architects, and solution developers. If you have any questions, just send a mail to [email protected], and you are likely get the answer to what you want to know. Recently Forgerock (http://www.forgerock.com) undertook an initiative to keep the community and product strong. They periodically fix the bugs in the open source branch. Their version of OpenSSO is called OpenAM, but the code base is the same as OpenSSO. Pretty much all of the examples and code cited in this book should work with the OpenAM as well. Nevertheless, there may be incompatibilities in future if OpenAM code base deviates a lot from the OpenSSO express build 9 code base. Note that the Oracle Open SSO Enterprise 8.0 update releases are based on the OpenSSO Enterprise release 8.0 code base, whereas the open source version OpenAM is continuing its development from the express build 9 code base. Throughout this book OpenSSO references can be interpreted as OpenAM as well with respect to the OpenSSO build 9 branch.

[ 10 ]

Download from Wow! eBook

Chapter 1

OpenSSO—an overview

OpenSSO is a freely available feature-rich access management product; it can be downloaded from http://www.forgerock.com/openam.html. It integrates authentication and authorization services, SSO, and open standards-based federation protocols to provide SSO among disparate business domains, entitlement services, and web services security. Overall, customers will be able to build a comprehensive solution for protecting their network resources by preventing unauthorized access to web services, applications, web content, and securing identity data. OpenSSO offers a complete solution for securing both web applications and web services. You can enforce a comprehensive security policy for web applications and services across the enterprise, rather than relying on developers to come up with ad hoc ways to secure services as they develop them. OpenSSO is a pure Java application that makes it easy to deploy on any operating system platform or container as it supports a broad range of operating systems and servlet containers. In this book, all of the features are not covered as the scope of the book does not permit to discuss all of them. Nevertheless, some of the core use cases are captured very well. For example, a separate chapter is devoted to discussing integrating the SaaS-based applications with OpenSSO infrastructure.

OpenSSO services

All the services provided by the OpenSSO are exposed over HTTP protocol. The clients access them using appropriate interfaces. OpenSSO exposes a rich library of Application Programming Interfaces (APIs) and Service Provider Interfaces (SPIs) using which, customers can achieve the desired functionality. These services developed for OpenSSO generally contain both a server component and a client component. The server component is a simple Java servlet developed to receive XML requests and return XML responses. The opensso.war web application (about to be introduced in the next chapter) encompasses all the services and associated configuration items that are required to deliver the OpenSSO functionality. The client component is provided as Java API, and in some cases, C API. This allows remote applications and other OpenSSO services to communicate with and consume the particular functionality.

[ 11 ]

Getting Started

Each core service uses its own framework to retrieve customer and service data and to provide it to other OpenSSO services. The OpenSSO framework integrates all of these service frameworks to form a layer that is accessible to all product components and plugins as shown in the following diagram:

Most of the core services are discussed in the forthcoming chapters. There are certain services that are not covered due to the scope of this book. Just to make you aware of the breadth of features provided by the OpenSSO, in the next few sections, some of the prominent features that are not covered in this book will be briefly introduced.

Federation services

Typically, in the web access management the Single Sign-On happens in the same company, within the same Domain Name Service (DNS) domain. Most of the time this will work for small companies or in B2C type scenarios, whereas in a B2B scenario use of a DNS domain-based SSO will not work as the cookie will not be forwarded to the other DNS domains. Besides, there are privacy and security concerns to perform SSO across multiple businesses using this approach. So how do we solve these kinds of problems where customers want to seamlessly sign on to services even though the services are provided by a third party? [ 12 ]

Chapter 1

Federation is the solution. So, what is federation? Federation is a process that establishes a standards-based method for sharing and managing identity data and establishing a Single Sign-On across security domains and organizations. It allows an organization to offer a variety of external services to trusted business partners, as well as corporate services to internal departments and divisions. Forming trust relationships across security domains allows an organization to integrate applications offered by different departments or divisions within the enterprise, as well as engage in relationships with co-operating business partners that offer complementary services. Towards the federation or solving SSO across multiple domains, multiple industry standards, such as those developed by the Organization for the Advancement of Structured Information Standards (http://www.oasis-open.org) (OASIS) and the Liberty Alliance Project (http://www.projectliberty.org/), are supported. OpenSSO provides an open and extensible framework for identity federation and associated web services that resolves the problems of identity-enabling web services, web service discovery and invocation, security, and privacy. Federation services are built on the following standards: • • • •

Liberty Alliance Project Identity Federation Framework (Liberty ID-FF) 1.1 and 1.2 OASIS Security Assertion Markup Language (SAML) 1.0 and 1.1 OASIS Security Assertion Markup Language (SAML) 2.0 WS-Federation (Passive Requestor Profile)

SAML 2.0 is becoming the de facto standard for the federation SSO as many of the vendors and service providers support SAML 2.0 protocol. For instance Google Apps and Salesforce support SAML 2.0 as their choice of protocol for SSO.

Web Services Security and Secure Token Service

The OpenSSO Web Services Stack follows a standardized way of integrating web-based applications using XML, SOAP, and other open standards over an Internet Protocol (IP) backbone. They enable applications from various sources to communicate with each other because they are not tied to any one operating system or programming language. Businesses use web services to communicate with each other and their respective clients without having to know detailed aspects of each other's IT systems. OpenSSO provides web services that primarily use XML and SOAP over HTTP(s). These web services are designed to be centrally provided in an enterprise's network for convenient access by client applications. OpenSSO implements and exposes about eight services that can be obtained by entering the following URL in your browser http://opensso-server.domain. net:port//identityservices, for example, http://opensso.packtservices.net:9090/opensso/identityservices. This URL follows the example that we will be using in later chapters. [ 13 ]

Getting Started

Before jumping onto securing web services, let us understand the concept of transport-layer security and message-level security. Transport-level security happens at the channel level. Transport-level security secures the communication at the channel level. For example, protocols such as TCP, HTTP, MSMQ, and so on have their own security mechanisms to secure their communication channel. SSL/TLS is predominantly used for securing the transport-level security. It is point-to-point security, which means the secure channel is guaranteed only to the end point between the consumer and the server. If the message passes through the intermediaries such as proxy or a load balancer before reaching the destination server then the rest of the communication channel must be secured, but that is something the sender cannot control. Potentially the message can be tampered by the intermediaries. Unlike the transport-level security, the message-level security is highly reliable as it secures the message itself. This means the message-level security is transparent to the underlying transport protocol. It is handled at the application level itself that is why it is often called application-level security or end-to-end security. This provides more flexibility as the application developer can decide which part of the message is to be signed or encrypted. In a large message it may be that only a smaller portion is required to be secured such as the authenticated identity's attribute. This message-level security is available as Web Services Security in OpenSSO and through the installation of a web services security agent such as the JSR196 Glassfish agent (http://jcp.org/en/jsr/detail?id=196). Web Services Security is the implementation of the WS-Security specifications and the Liberty Alliance Project Identity Web Services Framework (Liberty ID-WSF). Web Services Security allows communication with the STS to insert security tokens in outgoing messages and evaluate incoming messages for the same. Towards this end, authentication agents based on the Java Specification Request (JSR) 196 must be downloaded and installed on the Web Service Client (WSC) machine and the Web Service Provider (WSP) machine. To secure web services communications, the requesting party must first be authenticated with a security token which is added to the SOAP header of the request. Additionally, the WSC needs to be configured to supply message-level security in their SOAP requests and the WSP needs to be configured to enable message-level security in their SOAP responses.

[ 14 ]

Chapter 1

OpenSSO Entitlements Service

OpenSSO Entitlements Service is a brand new component introduced in OpenSSO express build 9. It is a fine-grained policy management solution that allows for centralized administration and evaluation of access control rules for enterprise applications and resources. As the entitlement market is maturing, more vendors have started supporting fine-grained policies including Oracle and IBM. OpenSSO Enterprise 8.0 does not have this feature. To fill this gap and catch up with the market, OpenSSO Entitlements Service is introduced in the express build 9. The IT architects and solution developers have always desired to externalize the authorization processing from business applications for centralized administration and to delegate the security code to security products. In the modern age of Web 3.0 development and deployments, it is increasingly important to adopt an architectural model where authorization and entitlement management are consumed as a service rather than embedded within business applications. OpenSSO Entitlements Service consists of Policy Policy Administration Point (termed as PAP) and Policy Evaluation Engine or Policy Decision Point (PDP). Additionally, there is Policy Enforcement Points (PEP) that is usually executed within the applications and enforces the policy decisions obtained from PDPs. Together, they provide a unified policy management, delegated policy administration, and distributed policy decision-making and enforcement. The existing policy management component of OpenSSO, which has a similar architecture as OpenSSO Entitlements Service, has the limitation of having a proprietary policy language. Its performance and scalability are acceptable only for coarse-grained policies and does not lend itself to a Service Oriented Architecture (SOA). The new component Entitlements Service will overhaul the policy management component by adopting eXtensible Access Control Markup Language (XACML) as the policy language. It has the ability to scale up to a million policies, and provide REST/ SOAP interfaces for policy management and evaluation. These enhancements will enable architects to externalize fine-grain authorization processing to OpenSSO and will enable developers to quickly develop PEPs for their applications. OpenSSO Entitlements Service is compatible with the existing policy framework and the current agents will continue to work with entitlements enabled. Both administrative console interfaces and command line interfaces are provided for the policy management. The interface is very intuitive to the administrative user.

[ 15 ]

Getting Started

What kind of problems does OpenSSO solve? You can challenge that not one single product in the Identity and Access Management arena offers the set of features that OpenSSO encompasses within it. It can solve a wide range of problems in the enterprise security domain.

You can deploy OpenSSO to solve the following four kinds of problems (OpenSSO can be used to address the these primary issues associated with balancing risk and reach):

Access management

The traditional challenge of internal SSO still exists for many organizations—and it's now compounded by the additional need for extranet authentication. Even if you've found a way to handle the former, the solution involved is not likely to be designed to take care of the latter. This problem can be solved by deploying the OpenSSO, thereby centralizing the server and agents' configuration as part of the embedded configuration store. The embedded configuration store is based on the highly performing embedded OpenDS. This reduces the cost of procuring another software to hold the configuration data. OpenSSO offers policy agents for all the popular web and application servers by installing the agents. The proxy model can also be leveraged for the SSO solution based on the deployment. Using the distributed authentication components the extranet access can be controlled. Overall the administrative cost can be brought drastically down by deploying the OpenSSO.

Federation

Federation provides an opportunity to expand business reach by providing more services through collaboration with partners. At the same time, if the customer wants to federate, he or she should be mindful of the need to secure these resources preferably in a repeatable, scalable way that accommodates growth. Employing OpenSSO-based solutions enables the customer to leverage the standards-based protocols that are supported including the OASIS Security Assertion Markup Language (SAML) 2.0.

[ 16 ]

Chapter 1

OpenSSO offers a truly lightweight means of federating: The Fedlet, a less than 10 megabytes in size package that identity providers provide to service providers so that they can federate back to a company without the need for any additional federation product. To become federation-enabled, the service provider simply adds the Fedlet to their application and deploys the application. No configuration is required, and it works with both Java and .NET applications. It provides an easy-to-use interface to validate service provider connections on-the-fly. Another feature called virtual federation proxy capability eliminates the need to have an already established SSO across the enterprise before being able to federate legacy authentication applications to service providers. The multi-protocol feature makes OpenSSO a perfect solution in the federated environment, wherein different providers in the circle of trust use heterogeneous federation protocols. OpenSSO is transparent to these protocols and can achieve SSO by leveraging the multi-protocol feature.

Securing web services

While many companies have invested considerably in centralized authentication and authorization for applications, few have done the same for web services. Now, however, many are recognizing the importance of abstracting web services away from the developer as part of an effort to standardize their security model across the organization. How can OpenSSO be used to secure web services? IT leverages the message-level security along with the Security Token Service to secure web service requests/ responses. It supports only standards-based solutions in the world to provide a pluggable, end-to-end secure web services solution. Web service developers can utilize the Netbeans IDE along with Glassfish to develop and test their web services. This expedites the development cycle as Netbeans inherently provides tools to enable the web service development. Besides, the embedded Security Token Service can be deployed as an integrated or a standalone solution to handle the security token issuance. As it is standards-based, all the token validation and translations are done via WS-Trust protocol. Customers can use the web services security agents as the policy enforcement point for the popular containers including the JBOSS application server.

[ 17 ]

Getting Started

Entitlements

The Entitlements Service in the OpenSSO express build 9 replaces the proprietary policy definition and evaluation engine with a more standards-based, highly scalable framework. Nonetheless, the new policy engine will continue to honor the old type of policy requests that are coming from the existing deployments. The motivation behind the new engine is to improve the administration, scalability, and performance. The new policy engine's performance benchmark will be in millions. The policy definition language will change from the proprietary format to OASIS XACML-based. With this change, one should be able to import and export policies easily from one vendor to another enabling the portability that might expedite the migration process. A new administrator user interface that is based on ICEFaces framework yields a better administration experience. The following diagram captures the salient features of these four problems and the solution provided by the OpenSSO server:

[ 18 ]

Chapter 1

Summary

In this chapter, we have covered the history of OpenSSO that dates back to early 2000 when Sun Microsystems started this as the Directory Server Access Management Edition (DSAME). It underwent multiple identity changes before fixing on OpenSSO. After Oracle acquired Sun Microsystems Inc., the OpenSSO product release models have changed a little bit, nonetheless, the existing OpenSSO customers continued to be supported by Oracle and patch releases have been happening for the paid OpenSSO enterprise customers. On the open source front, the company called http://www.forgerock.com took the leadership in maintaining and developing further on the OpenSSO source code. Their version is not much different from OpenSSO express build 9 source code branch, yet it is called OpenAM, perhaps due to licensing and trademark reasons. We have also briefly looked at the overall architecture of OpenSSO to understand the whole product's features before discussing some of the core problems in the security domains and how OpenSSO can be employed to solve such problems. In the next chapter, we will be taking a deep dive into OpenSSO product installation and configuration.

[ 19 ]

OpenSSO Deployment and Configuration By now you should be familiar with OpenSSO and the supported protocols, specifications and associated terminologies. This chapter takes you through the steps of setting up your operating environment with a supported web container, supported identity, and configuration stores. After completing this chapter you will be able to build OpenSSO from source code, and you will be able to configure the product in a single or multi-server deployment configuration. You can also find some tips and procedures to automate the configuration in a non-interactive environment using the command line utility provided by OpenSSO. In the last part of this chapter, I have included some pertinent information about the OpenSSO release model and the details on how to obtain support for your specific version of OpenSSO (whether it is the enterprise or open source version) deployment from Oracle Inc., or Forgerock (http://www.forgerock.com). If you are planning to deploy OpenSSO for some serious revenue impacting business, it is recommended that you buy the OpenSSO Enterprise release support from Oracle. Of course, you have the option of deploying the open source version from Forgerock. This chapter covers: •

Environmental requirements for OpenSSO

•

Deployment

•

Configuration

•

Uninstalling OpenSSO

•

OpenSSO release and support model

OpenSSO Deployment and Configuration

Deployment requirements for OpenSSO web application

The OpenSSO product is a Java Web Archive (WAR) application which does not require any other external components such as a Database or LDAP server to configure the basic vanilla server. It can be deployed on any servlet 2.4/2.5-compliant web container. This can be readily deployed to any container by just copying the WAR file to the auto deployment directory if the container supports automatic web application deployments. For example, in the Apache Tomcat server, it can be easily deployed by copying the opensso.war (Refer to section OpenSSO—configuration choices, included later in the chapter) to the webapp directory of the Tomcat container. Once you copy the WAR file, it automatically deploys the application and the configurator will be available at the following URL: http://tomcatserver:port/opensso.

Containers and operating systems support In order to deploy the OpenSSO web application, you need to have one of the containers in the supported platform, as described in the following table: Container

Version

Operating environment

Apache Tomcat

5.5.27

Windows XP/VISTA/2003/2008 Solaris 9,10 Redhat Linux 3/4/5 Ubuntu 8.x/9.x OpenSolaris

6.0.18

Glassfish

v2U1,v2U2

Windows XP/VISTA/2003/2008 Solaris 9,10 Redhat Linux 3/4/5 Ubuntu 8.x/9.x OpenSolaris

Glassfish EE

2.1/9.1

Windows 2003/2008 Solaris 9,10 Redhat Linux 4/5

Oracle WebLogic

10.3

Windows 2003 Solaris 9,10 Redhat Linux 4/5

Oracle Application Server

10g

Windows 2003 Solaris 9,10 Redhat Linux 4/5

Sun Application Server

[ 22 ]

Chapter 2

Container

Version

Operating environment

IBM WebSphere Application Server

7

Windows 2003 Solaris 9,10 Redhat Linux 4/5 AIX 5.3

JBOSS

5.1

Windows 2003 Solaris 9,10 Redhat Linux 4/5

Geronimo

02/01/01

Solaris 10

All the minor updates of these versions are supported.

Java SDK support

OpenSSO leverages certain features from the container's Java SDK, and the server is tested and certified on these specific versions of the Java SDKs. Using these versions ensures that you experience consistent functionality and performance from OpenSSO. Mostly the Java virtual machines (JVMs) that come with the containers are certified by the OpenSSO test team. The following table lists out the supported Java versions for the OpenSSO server and the client applications. Java version

OpenSSO server

OpenSSO Client

Java SDK 1.7*

X

X

Java SDK 1.6

X

X

Java SDK 1.5

-

X

*Developer Platforms GFv2 and Tomcat

IBM Java and Oracle Weblogic Jrocket are also supported on their respective containers.

Disk and memory requirements

For a developer level deployment, typically you should have a 200 MB disk space and 1 GB memory to build and deploy a single instance of OpenSSO. For running multiple instances of OpenSSO in the same host you may want to scale the memory requirements accordingly.

[ 23 ]

OpenSSO Deployment and Configuration

Browser requirements

OpenSSO can be accessed and managed by using most of the popular web browsers, such as Firefox 3.0 and Internet Explorer 7. Browsers should be configured to accept cookies and Java Script.

Configuration store versus Identity Store Quite often users get confused with the Configuration store and the Identity Store (also called User store or User repository). Let us be clear on this terminology because we will deal with these terms throughout this book. It is critical to know the distinction between these two repositories to better understand the OpenSSO concepts.

Configuration store

Configuration store or Configuration repository is used to store the configuration information of the OpenSSO server. This is the core part of the server that provides crucial information to start up the services provided by OpenSSO. If this store is down, then the OpenSSO server will not even start successfully. This repository contains critical pieces of configuration information, including: •

Host name, port, URIs of the OpenSSO server(s), and services

•

List of services supported and their configuration details, such as Authentication and Audit

•

Policy information to provide authorization services

•

Realms and realm-specific configuration

•

Information about the Identity stores configured for the realms

•

Information about the servers that provide failover capability to support high availability

•

Centralized configuration data of OpenSSO policy agents and Web Service Clients

•

Information about administration of OpenSSO

At the time of writing (OpenSSO Express Build 9) OpenSSO supports a built-in embedded configuration store, as well as a highly scalable external Sun Java System Directory Server store.

[ 24 ]

Chapter 2

The embedded store is part of the opensso.war that does not require any pre-configured Sun Java System Directory Server. This embedded store is sufficient for a medium-sized deployment. For larger deployment with high availability and scalability requirements, it may be worth using Sun Java System Directory Server as the configuration data store.

Embedded configuration store

Embedded configuration store is based on the OpenDS which is a pure Java-based LDAPv3 compliant directory server, open source and is available via CDDL license (https://www.opends.org/). Using embedded store is the quickest and easiest way to bring up the OpenSSO server. Besides, it does not involve any cost. However, using Sun Java System Directory Server for storing configuration data requires you to buy the software from the vendor. On the other hand, the Java servlet container's JVM is responsible for running and managing the embedded store, as shown in the following diagram, and this puts extra load on the container subsequently limited by the JVM performance. Throughout this book, all the examples are generated with embedded configuration store unless mentioned otherwise. Even though the configuration store is based on OpenDS, you cannot manage this using the OpenDS tools that you can download from https://opends.dev.java. net/. The specific version that is embedded is highly customized and fine-tuned for the OpenSSO product. The existence of the OpenDS port is supposed to be treated as black box by the OpenSSO administrators and users. To manage the configuration data, OpenSSO does provide both GUI and command line interfaces.

[ 25 ]

OpenSSO Deployment and Configuration

In the default configuration, the configurator (refer to section Configuring OpenSSO) does create a user identity store that points to the embedded configuration store. This user store is meant to be used to validate the OpenSSO configuration and functionality, such as Single Sign-On (SSO) verification with the SAMLv2 provider. Creating and managing user identities in embedded store at a large scale is not something that is a recommended practice. It is always recommended to use a separate identity store such as OpenDS with OpenSSO.

External Sun Directory Server Enterprise Edition configuration store

For most of the deployments, using built-in embedded configuration store would be sufficient and cost effective. Nevertheless, for applications that require high availability and scalability it may be worth considering Sun Java System Directory Server as the configuration store. With this kind of configuration, it is possible to achieve the highest level of availability and scalability that is supported by the OpenSSO product. Having an external directory offers distinct advantages of keeping the container and configuration store separate, as shown in the following diagram:

[ 26 ]

Download from Wow! eBook

Chapter 2

This takes the burden off managing the embedded configuration store from the container's Java Virtual Machine. Only the Sun Java Directory Server supports the configuration store. None of the other LDAPv3 compliant servers including an externally configured OpenDS, Microsoft Active Directory, and IBM Tivoli Directory Server are supported. The table in this section outlines the supported directory servers for the OpenSSO configuration and identity store. Store type

Version

Configuration store

Identity store

Sun Directory Server Enterprise Edition

5.2, 6.3, and 7.0

X

X

Embedded Store

2.x

X

X

Microsoft Active Directory

Windows 2003 and Windows 2008

Not Supported

X

Microsoft Active Directory Application Module(ADAM)

Windows 2003 and Windows 2008

Not Supported

X

IBM Tivoli DS

6.1

Not Supported

X

Access Manager Respository(amSDK)

Sun Java System Directory Server 5.2, 6.3, and 7.0

Not Supported

X

Externally Configured OpenDS

2.x

Not Supported

X

MySQL

5.1

Not Supported

X (Early Access)

MySQL and Embedded Store has limited support for the identity store.

Identity store

In the OpenSSO terminology, an identity can represent one of the following four entities: user, group, role, or filtered role. All of these entities will be stored in one of the supported identity stores also synonymous with the user store. An OpenSSO server instance can have more than one identity store in a realm or across multiple realms. The services running as part of the OpenSSO web application consume the identities stored in the identity repositories for authentication and authorization purposes.

[ 27 ]

OpenSSO Deployment and Configuration

Technically an OpenSSO server can exist without a data store configuration to start with, because the administrative user called amadmin (this username is hardcoded and cannot be changed) is stored in the configuration store. This enables the administrator to log in to the server even if the user store that provides authentication is down. All the identity names are case insensitive from the processing perspective. However, the administrative console and other utilities display the identities as you have created them. For instance, you can log in to OpenSSO by entering amAdmin or amadmin in the username field, and both will let you access the console as long as the password is correctly entered. Of course, passwords are case sensitive. There is a separate section devoted to these identity stores due to their importance. We will revisit this topic in greater detail in the later part of this book.

How to obtain OpenSSO

The source code and binary of OpenSSO is available under CDDL license (http://www.sun.com/cddl/cddl.html). There are two ways to get the binaries. One way is apparently to build from the source; the other is to simply download a stable released version of 'express' or 'enterprise' build. Downloading the binary form of this product is the quickest way to get started with OpenSSO. In this section you can find the relevant resources and pointers on building the OpenSSO from the source code. For the examples, we would use the latest stable build from the binary download page of OpenSSO.

Building OpenSSO from source

If you want to build OpenSSO from the source, the first thing you need to do is to sign up at https://opensso.dev.java.net/ in order to obtain CVS repository access to the source code. Once you sign up and have been approved for the appropriate "developer" or "observer" role, you can check out the source code using the cvs checkout command. For example: cvs -d :pserver:memberName @cvs.dev.java.net:/cvs checkout opensso

where memberName is your OpenSSO member name. For example to check out the OpenSSO Express Build 9 branch: % cvs -d :pserver:[email protected]:/cvs checkout -r opensso_build9_branch opensso [ 28 ]

Chapter 2

In order to build OpenSSO web archive file, there are a number of steps that need to be performed, including downloading some third party shared libraries. This process is documented very well. This is a living document, so it will be frequently updated. It does not add much value to reproduce the same (but changing) information in this book. Please point your browser to https://opensso.dev.java.net/public/use/ builds/instructions.html to obtain the latest version of the document. As I mentioned in the Chapter 1, to obtain the latest open source version of OpenSSO, please visit the Forgerock site (http://www.forgerock.com/), as they maintain and sustain this source branch with the name OpenAM.

Downloading OpenSSO binary

Originally when Sun Microsystems started the OpenSSO project, the binary was available in three different forms, nightly, express, and enterprise builds. After the Oracle/Sun merger only OpenSSO enterprise builds were released and supported by Oracle through its support/sales channels. You can download the build at http://www.forgerock.org/downloads/openam_release9_20100207.zip which is closer to the build that was used to generate the examples used in this book. You can find the other binary download links for the various builds in the OpenAM project website at http://www.forgerock.org/. The examples and directory structure are generated on a Linux-based system, yet any discrepancy between Windows and Unix will be noted wherever possible. You can use http to download or a wget to download the build 9 bits. The following command downloads the binary using the wget command on a Linux host: wget http://www.forgerock.org/downloads/openam_release9_20100207.zip

[ 29 ]

OpenSSO Deployment and Configuration

Now that you have downloaded the zip file that contains the OpenSSO war file, let us unzip and look at the contents and the directory structure:

All the directories are shown in the directory structure that we saw. The contents of these directories are not mentioned to improve the readability. The contents of these directories will be explained as we progress through this book. The opensso.war under the deployable-war directory is the OpenSSO web application. This is the WAR that gets deployed on to servlet containers. Now that all the theory is over, let us get into some real hands-on sessions. The next few sections take a deep dive into the deployment and configuration of the OpenSSO web application and its configuration utility. There is a browser-based configurator as well as a command line configurator. The command line interface to the configurator greatly eases configuration automation tasks. [ 30 ]

Chapter 2

Configuring OpenSSO

As you know it is deployable on almost all the popularly available commercial as well as freely available open source web containers. Refer to the first table in this chapter for more information on this. To be more open source friendly, all the hands-on examples are devised and performed on Apache Tomcat and Linux Operating systems unless the underlying feature requires other Operating Environments. The product can be configured in many ways based on the deployment use cases; not all the specific deployment options are exercised in this book, only the frequently used meaningful cases are used, and the rest of the cases are left as an exercise to the readers.

Installing and configuring Apache Tomcat 6.0.20

In order to deploy the application, we should prepare the web container that will host the OpenSSO web application. We are planning to use the popular Apache Tomcat servlet container which can be downloaded from the URL: http://tomcat.apache.org/download-60.cgi#6.0.20. OpenSSO does not impose any special privileges in order to be deployed and configured. For this example, let us use a separate user ssouser who belongs to the group ssogroup with a valid home directory location. On the Windows Operating System, you can use a normal user since OpenSSO does not write anything into the Windows Registry. In general, the OpenSSO configurator writes all the information in a directory of the user's choice except the bootstrap file locator that is placed in the web container's runtime user's home directory. In this example it will be placed in the ssouser's home directory. The following sequence of commands invoked in the bash shell environment downloads, unzips, and configures the Tomcat Server 6.0.20 version: ssouser@opensso[1] > id uid=54951(ssouser) gid=54031(ssogroup) groups=54031(ssogroup) context=use r_u:system_r:unconfined_t ssouser@opensso[2] > pwd /export/ssouser ssouser@opensso[3] > wget -q http://www.poolsaboveground.com/apache/ tomcat/tomcat-6/v6.0.20/bin/apache-tomcat-6.0.20.zip

[ 31 ]

OpenSSO Deployment and Configuration ssouser@opensso[4] > export JAVA_HOME=/usr/jdk/linux-i586/ ssouser@opensso[5] > $JAVA_HOME/bin/java -version java version "1.6.0_14" Java(TM) SE Runtime Environment (build 1.6.0_14-b08) Java HotSpot(TM) Server VM (build 14.0-b16, mixed mode) ssouser@opensso[6]> ls -l apache-tomcat-6.0.20.zip -rw-r--r-zip

1 ssouser ssogroup 6379115 May 29

2009 apache-tomcat-6.0.20.

ssouser@opensso[7] > unzip -q apache-tomcat-6.0.20.zip ssouser@opensso[8] > ls -F apache-tomcat-6.0.20 bin/

lib/ logs/ RELEASE-NOTES

conf/

LICENSE

temp/

NOTICE RUNNING.txt

work/ webapps/

ssouser@opensso[9] > cd apache-tomcat-6.0.20/bin ssouser@opensso[10] > chmod +x *.sh ssouser@opensso[11] > export JAVA_OPTS="-Dcom.iplanet.am.cookie. c66Encode=true" ; export CATALINA_OPTS="-Xmx1024m" ssouser@opensso[12] > ./startup.sh Using CATALINA_BASE:

/export/ssouser/apache-tomcat-6.0.20

Using CATALINA_HOME:

/export/ssouser/apache-tomcat-6.0.20

Using CATALINA_TMPDIR: /export/ssouser/apache-tomcat-6.0.20/temp Using JRE_HOME:

/usr/jdk/linux-i586/

Here is a simple explanation of each command: 1. It prints the current logged in user's login name and group. 2. Shows the current working directory, which happened to be the ssouser's home directory in this case. 3. In this step, we download the Tomcat server binary from the URL mentioned there. 4. Setting the JAVA_HOME environment variable that points to a valid JDK 1.6 location. 5. Making sure the JDK is the required version 1.6+. 6. Make sure the Apache Tomcat binary is available in the current directory. 7. Unzip the binary to the local directory. This will create a new directory with the version name in it. 8. Display the contents of the unzipped directory.

[ 32 ]

Chapter 2

9. Change directory to the Tomcat bin where the start and stop scripts are located. 10. Enable execute permissions for the scripts in this directory. 11. You need to set these options to start the OpenSSO application successfully after deployment. It is recommended you make these changes to the catalina.sh to avoid typing this every time. 12. This command starts up the Tomcat server, here we assume that the default ports are available in the localhost, where you perform these steps. The default service port for http traffic is 8080. In a production level deployments OpenSSO server and policy agents will be deployed in different physical hosts. For simplicity, we use the same physical host to deploy multiple instances of OpenSSO and agents. We can achieve this by using the /etc/ hosts aliases. Make sure that your naming resolver in the /etc/ nsswitch.conf looks for files first. You do not need to worry about naming resolution if you are using a standalone system.

We are going to call our OpenSSO as http://opensso.packt-services.net:8080. To make this happen, add the following in your /etc/hosts: 192.168.1.10

opensso.packt-services.net

If you are using a standalone host, such as a laptop, just add the virtual host alias against the loop back interface. After adding the previous alias, you can access the Tomcat server: http://opensso.packt-services.net:8080/index.jsp

If you are accessing the server from another client computer, then you need to add the IP address of the OpenSSO server followed by the alias in your local client as well. Here's an example: 192.168.1.10 opensso.packt-services.net

Now we are all set to start the OpenSSO deployment.

[ 33 ]

OpenSSO Deployment and Configuration

OpenSSO one click configuration

In the next section, you can find the various configuration types and their use case scenarios. To get started right away with OpenSSO, use the one click configuration feature. It does not ask for any information except two non-unique passwords. This is the best way for the newbies to get started on OpenSSO. Copy the opensso.war from the /opensso/deployable-war directory to the Tomcat webapps directory (Refer to Downloading OpenSSO binary discussed earlier in this chapter): cp /opensso/deployable-war/opensso.war apache-tomcat-6.0.20/webapps

/export/ssouser/

This process will automatically deploy the OpenSSO web application. Now you can access the configurator by using the URL: http://opensso.packt-services. net:8080/opensso/config/options.htm. Upon invoking the configurator, the browser will render a page similar to the one shown in the following screenshot if the deployment of the web application is successful.

[ 34 ]

Chapter 2

In this page there are two options for the administrator who would like to configure the server. Default Configuration is the simplest option to bring up the OpenSSO server for a novice user; it does not ask too many questions. As you can see in the following screenshot, it asks only two questions that are password-related. However, the next option Custom Configuration is meant for advanced deployment use cases where one can configure multiple server instances, with a custom configuration data store.

[ 35 ]

OpenSSO Deployment and Configuration

Now you select the Default Configuration link and provide the password for the Default User (Default User is amadmin), as shown in the preceding screenshot. This is the top level administrative user for the whole OpenSSO server. This is similar to the Unix root or Windows Administrator user, so make sure you secure and remember the password that you have entered in this screen. Also note that the configurator will not let you use the same password for both of these users for security reasons.

When you click on the Create Configuration button, a progress window will show you the actions of the configurator including creating the embedded configuration store and loading the OpenSSO service schema among others. Once the configuration is successful, a pop-up dialog (as previously shown) will notify that the server is ready to use.

[ 36 ]

Chapter 2

This completes the configuration of the OpenSSO server with all default settings except the passwords for the administrative users.

Verifying OpenSSO configuration

There is more than one way to verify the sanity of the server. From the browser, you can access the login page by entering this URL: http://opensso.packt-services.net:8080/opensso/UI/Login

You can also verify the server sanity by using the REST interfaces. Just enter: http://opensso.packt-services.net:8080/opensso/identity/authenticate? username=amadmin&password=secret12

[ 37 ]

OpenSSO Deployment and Configuration

This will return an SSO token if the server is up and running, and here secret12 is my password for the amadmin user. The server will respond back with a default authentication module where you can enter the amadmin user and its password to get into the system. Upon successful authentication, you will be taken to the default landing page. From here you can start your OpenSSO administrative activities (Refer to Chapter 3 for more details on how to administrate the OpenSSO server).

If you have reached this stage without any issue then give yourself a pat on the back. It is a great milestone to achieve.

What just happened?

The OpenSSO server is configured into a location under the web container runtime user's home directory. A directory with the name of the deploy URI (in this case it is opensso) will be created under the user's home directory. It means all the configuration information will be placed under /export/ssouser/opensso. There will also be a directory named .openssocfg created under /export/ssouser (this is the $HOME of ssouser):

[ 38 ]

Chapter 2 [ssouser@opensso]:/export/ssouser> ls -F apache-tomcat-6.0.20/

opensso/

[ssouser@opensso]:/export/ssouser> ls -F opensso amAuthSafeWord.xml

am_sm_ds_schema.ldif

install.log

amAuthUnix.xml

bootstrap

opends/

am_remote_opends_schema.ldif

config/

opensso/

am_sm_ad_schema.ldif

fam_sds_schema.ldif

template/

[ssouser@opensso]:/export/ssouser> ls .openssocfg/ AMConfig_export_ssouser_apache-tomcat-6.0.20_webapps_opensso_ [ssouser@opensso]:/export/ssouser> more .openssocfg/AMConfig_export_ ssouser_apache-tomcat-6.0.20_webapps_opensso_ /export/ssouser/opensso

As you can see, this file (called bootstrap locator) has the location of the configuration directory which contains the file called bootstrap. This file provides the critical information to bring up the OpenSSO server. If this file does not exist or is not readable by the web container process, then OpenSSO assumes the web application is not configured. Subsequently, it will show the configuration page as if the product has not been configured. When the OpenSSO web application initializes, it locates the configuration information (if already configured) from the bootstrap locator file available in the $HOME/.openssocfg directory. Note that this type of configuration will create an embedded user identity store by default. You can delete and recreate a supported external identity store. Configurator does load the user identity schema as part of the configuration process. We can see a more detailed description of the content of these directories in a later section of this chapter.

OpenSSO–configuration choices

It is possible to customize the OpenSSO deployment based on the customers' requirements. The configurator provides extensive options to customize the configuration of the server including the choice of configuration, identity stores, root suffix, and file system location for the configuration data. In this section, let us look at the most frequently used custom configurations:

• •

Single server with customized configuration data, using embedded configuration store Single server with customized configuration data using the external Sun Java System Directory Server configuration store Multiple server instances with replicated embedded configuration store Configuration of single server using command line configurator

•

Configuration of OpenSSO with SSL/TLS

• •

[ 39 ]

OpenSSO Deployment and Configuration

There are a few other choices available in the configurator, but the preceding use cases address them in one way or the other.

Single server configuration–using embedded configuration store

Earlier, in the section titled OpenSSO one click configuration we have briefly seen how OpenSSO can quickly be configured in a single-click procedure. It just works perfectly fine with no loss in functionality. However, if you remember, only the passwords were supplied and no other questions were asked during the configuration stage. In real customer deployments, they would not be using the default choices provided by the configurator. For instance, the root suffix of OpenSSO is set as default to dc=opensso,dc=java,dc=net but typically, customers will be wanting to use their business name as the root suffix. Such kinds of data can be provided using the customized configuration page. Let us assume the same Tomcat scenario as in the section Installing and configuring Apache Tomcat, except OpenSSO is deployed but not configured. An OpenSSO embedded configuration can be easily cleaned up by just removing the configuration directory and bootstrap locator file from the web container runtime user's home directory. In the example shown in the section Configuring OpenSSO if /export/ssouser/.openssocfg/ AMConfig_export_ssouser_apache-tomcat-6.0.20_webapps_ opensso_ and /export/ssouser/opensso are removed, then the web application will automatically show the configurator page.

To customize the OpenSSO server with the embedded configuration store, invoke the configurator and select the Create New Configuration option (refer to the first screenshot in this chapter). This lets you customize the server configuration information. In the next few configuration steps, the OpenSSO configurator will ask specific questions related to your deployment, and provide proper values at each step to progress further. It does validate the information provided by making use of AJAX technology. For example, if you have entered external identity store details, then it internally validates by making a LDAP bind request. If the bind operation is not successful then an error will be shown in the configurator. This kind of validation helps to eliminate the human errors made while entering the values.

[ 40 ]

Download from Wow! eBook

Chapter 2

At the custom configuration step (preceding screenshot), entering a password for the amadmin user involves the same process as that for the one click configuration. Let us focus our attention on the following screenshot:

[ 41 ]

OpenSSO Deployment and Configuration

In the preceding screenshot, the configurator automatically picks up the Server URL from the browser. Server URL

It is the base URL at which all the OpenSSO services are exposed.

Cookie Domain

This is very critical information for OpenSSO to set the cookies. The clients, such as policy agents, rely on this to participate in SSO. If you are on a standalone host, you can enter the loopback address in this field..

Platform Locale

This forms the default locale for the OpenSSO server.

Configuration Directory

Writable directory by the web container's runtime user to place all the server-specific configuration files. If it is using an embedded configuration store, then all the database files are placed in this directory.

After you provide all the above details, configurator tries to determine whether you would like to configure a new instance or add another server to an already configured OpenSSO server, by probing the administrator who invoked the configurator.

As you can see, it provides two options—First Instance and Add to Existing Deployment. Most of it is self-explanatory. The first instance means, it is a single server configuration. Add to Existing Deployment allows you to perform multiple server instances sharing the same configuration. We will see that in a little while. For now, select the First Instance and proceed. In all of the screenshots, the Next and Cancel buttons are not shown just to save the space for text. [ 42 ]

Chapter 2

Configuration Data Store

This field determines whether the server will use the embedded configuration store (labeled as OpenSSO) or an externally configured Sun Java System Directory Server.

SSL Enabled

This field is used if the configuration store is running in SSL/ TLS, applicable only to the externally configured Sun Java System Directory Server.

Host Name

Host name of the directory server for embedded and it defaults to localhost.

Port

Port number at which the LDAP server is running.

Encryption Key

It is a random string generated by the configurator. It is used by OpenSSO to encrypt critical information, such as passwords of administrative users in the local file system. This must be at least 10 characters long. For readability a sample value is provided.

Root Suffix

This is the base suffix of the OpenSSO. It often relates to the root realm (/).

[ 43 ]

OpenSSO Deployment and Configuration

From the configurator, you can create the user identity store for any of the supported LDAP servers. An OpenSSO User Data Store means the identity store will be pointing to the same store as the configuration store. This option may be chosen for a development environment. For production deployments, it is recommended to use one of the Other User Data Store that supports most of the commercially available directory repositories as shown in the previous screenshot. User Data Store Type

Provides options to select the appropriate user store based on your existing infrastructure. You could choose any of the supported stores. In this case, I have chosen Sun Java System Directory Server. During the configuration, custom schema, indexes, and some administrative users are created in the user identity store.

SSL Enabled

This should be enabled if the identity store is configured to run over SSL/TLS.

Directory Name

Name of the host where the user store is running.

Port

LDAP(s) service port.

Root Suffix

Root suffix of the identity store. This could be different from the configuration root suffix. In this case, it is o=packt-users.com.

Login ID

A Bind DN that has proper access privileges to add schema and entries under the root suffix.

Password

Password for the Bind DN. Configurator will try to use the credentials to make sure the above information is correct. If not, the Next button will be disabled.

In the next step of the configuration, it is time to decide whether you want to add this server to an already existing site or create a new site. Let us defer this discussion of sites to the next section. [ 44 ]

Chapter 2

The last part of the configuration process is to supply the password that will be used as the shared secret for the policy agents who are designed to operate with this shared secret. This password must be different from the top level administrative user amadmin as shown in the following screenshot:

That's pretty much it! The following two configurator screenshots provide you with a summary of the configuration data acquired from the user so far, and a progress page of the configuration tasks.

[ 45 ]

OpenSSO Deployment and Configuration

A pop-up window will notify whether the configuration of the server was successful, then you can proceed with the login verification.

Now you can perform the usual sanity check on the configured server.

Layout of the configuration directory

All the OpenSSO configuration information is placed in the configuration directory that you supplied during configuration of the server. In the case of the external configuration store, all the server configurations are stored in the external directory. Let us look at some important files that are supposed to be present here: bootstrap config/

install.log opends/ ldif/ opensso/

template/

The file bootstrap will be present in the configuration directory irrespective of the configuration store type. This file is consulted by the OpenSSO web application during initialization. It contains the configuration repository hostname, service port, and user credentials: [ssouser@opensso]:/export/ssouser/opensso-custom-config> more bootstrap ldap://localhost:5389/http%3A%2F%2Fopensso.packt-services. net%3A8080%2Fopensso?u ser=cn%3Ddsameuser%2Cou%3DDSAME+Users%2Cdc%3Dopensso%2Cdc%3Dpacktservices%2Cdc% [ 46 ]

Chapter 2 3Dnet&pwd=AQIC5wM2LY4SfcxifefYId8kNEnAbo3t4UH8&dsbasedn=dc%3Dopensso%2Cdc %3Dpack t-services%2Cdc%3Dnet&dsmgr=cn%3DDirectory+Manager&dspwd=AQIC5wM2LY4S fcxifefYId8 kNEnAbo3t4UH8&ver=1.0

As you can see, there are some usernames and their encrypted credentials stored in this file. In a multi-server scenario, there will be multiple entries present in this file. This file will be a read-only for the web container's runtime user, no one else is supposed to have access to this file by design. The next directory is named opensso. This could be anything. Basically it is named after the deployment URI of the OpenSSO web application. It serves the purpose of holding the audit and debug logs for the server. There are two hidden files, .configParam and .version. The former saves the configuration parameters of your OpenSSO server, and the latter has the version information of the server. As the name suggests, opends is the directory that holds all the embedded configuration store. This directory will not be there if the configuration store of OpenSSO points to a remote Sun Java System Directory Server. OpenSSO comes with a default key store keystore.jks. This will be used for all the signing and encrypting of data wherever required. The rest of the files and directories are stored for reference and audit purposes, and in some cases it is used to customize OpenSSO further.

Single server configuration–using external configuration store

In this scenario, the configuration data of the server will be written to an externally pre-configured Sun Java System Directory Server. Customers may choose this option when they need to support a huge number of policies in the OpenSSO server. Apparently, this deployment choice will yield better scalability and performance of OpenSSO. You need to make sure the external Sun Java System Directory Server is already configured with proper security and privileges. OpenSSO configurator loads some custom schema, adding index to Sun Java System Directory Server. Again, only Sun Java System Directory Server supports the configuration store. None of the other LDAP servers are allowed for this purpose.

[ 47 ]

OpenSSO Deployment and Configuration

The configuration procedure is the same as that of the previous section, using embedded store, except that you would select the configuration store as external Sun Java System Directory Server at step three of the configuration.

The bind distinguished name (DN) configurator defaults to cn=directory manager, but it is recommended to use a custom user DN for this purpose. This DN needs to have privileges to add schema, create indexes, and all privileges to the root suffix of the OpenSSO. The root suffix of OpenSSO need not necessarily be the root suffix of the directory server, it could be the sub suffix as well. Following LDIF creates the custom user DN and associated privileges for Sun Java System Directory. You need to add this using appropriate ldapmodify command options: dn:cn=schema changetype:modify add:aci aci:(target="ldap:///cn=schema")(targetattr="*")(version 3.0; acl "Configurator user rights to load schema"; allow (all) userdn = "ldap:///cn=puser,ou=DSAME Users,dc=opensso,dc=packt-services,dc=net"; ) dn:cn=plugins,cn=config changetype:modify add:aci [ 48 ]

Chapter 2 aci:(target="ldap:///cn=plugins,cn=config")(targetattr="*")(version 3.0; acl "Configurator user rights to load schema"; allow (all) userdn = "ldap:///cn=puser,ou=DSAME Users,dc=opensso,dc=packtservices,dc=net"; ) dn:dc=opensso,dc=packt-services,dc=net changetype:modify add:aci aci:(target="ldap:///dc=opensso,dc=packt-services,dc=net") (targetattr="*")(version 3.0; acl "Configurator user rights to write to the Suffix"; allow (all) userdn = "ldap:///cn=puser,ou=DSAME Users,dc=opensso,dc=packt-services,dc=net"; ) dn: ou=dsame users,dc=opensso,dc=packt-services,dc=net objectClass: top objectClass: organizationalUnit dn: cn=puser,ou=DSAME Users,dc=opensso,dc=packt-services,dc=net objectclass: organizationalperson objectclass: person objectclass: top cn: puser sn: puser userPassword: secret12

Once you add the preceding code, you will be able to use the cn=puser,ou=DSAME Users,dc=opensso,dc=packt-services,dc=net as your configuration DN as

shown in the preceding screenshot. The rest of the configuration steps, including selection of user identity stores, remain the same. However, you will not be able to select the OpenSSO user store as it is applicable only for the embedded configuration store option. In the external configuration store, a persistent search connection is established between the directory server and the OpenSSO server to push the change notifications that occur at the directory server side. In the embedded store case, everything is running in the same Java VM, where the in-memory notifications are sent to OpenSSO for the changes. There are situations where the configurator will fail before even completing the configuration. In this case, one cannot get adequate logs to debug further. You can get around these kinds of scenarios by adding -Dcom.iplanet.services.debug.directory=/tmp/debug and -Dcom.iplanet.services.debug.level=message Java VM options to the web container. Now the debug information will be available under the /tmp/debug directory.

[ 49 ]

OpenSSO Deployment and Configuration

Multi-server configuration–embedded configuration store

When the deployment demands a high availability requirement for the services provided by OpenSSO, you need to have more than one server instance to achieve that. In the multi-server configuration, all the servers share the same configuration data even though physically they are connecting to different directory server ports. These directory servers are replicating their data using the replication protocol of OpenDS/Sun Java System Directory Server, as applicable. When you use the embedded configuration store the replication (basically, replication between the embedded OpenDS servers) of configuration data is done automatically by the OpenSSO configurator. There is no special pre or post setup required for the configuration data replication. However, the external configuration with Sun Java System Directory Server requires replication to be set up before or after configuration of OpenSSO. Setting up the Sun Java System Directory Server's directory servers and replicating them are beyond the scope of the configurator as well as this book. In the multi-server instance case, each server is designed to serve the request that may have been originally served by another server in the same server farm or site. A site in OpenSSO terminology is a collection of servers in the same geography, region, or business unit sharing identical configuration data. When one of the servers goes down in the region, the existing user's session is automatically routed (provided the OpenSSO session high availability, also termed as Session Failover, is enabled) to the next available server, so that the end user would see no service interruptions. This is how the high availability is achieved. With no session high availability enabled, the request level failover will work with site configuration, however the user will be asked to re-authenticate when the OpenSSO server that issued the session goes down.

[ 50 ]

Chapter 2

Prerequisites for multi-server configuration

In the multi-server configuration, you need to configure the first OpenSSO server as a stand alone instance. Then access the second (or any subsequent instance) instance's configurator, to point the first server's naming URL. It automatically gathers the configuration information after authenticating as amadmin user. There can be more than two servers in a multi-server OpenSSO deployment. The following are the minimum requirements for a multi-server deployment with request level failover capability: •

At least two OpenSSO web applications deployed with the same deployment URI name (example is opensso)

•

One of the OpenSSO servers already configured

•

A HTTP load balancer configured properly between two OpenSSO servers

For this exercise, let us assume there are two servers involved with the HTTP Load Balancer (LB) in front. This could be a hardware or a software load balancer. Two instances of Apache Tomcat servers are used with HAProxy, a freely available HTTP load balancer. OpenSSO Server 1 opensso1.packt-services.net:8080 LB URL

OpenSSO Server 2 opensso2.packt-services.net:9090 http://opensso-lb.packt-services. net:80

HAProxy is a freely available HTTP load balancer (LB). There are a lot of articles available on the internet to configure it. (http://www.softwareprojects.com/

resources/programming/t-how-to-install-and-configure-haproxy-as-anhttp-loa-1752.html). The assumption here is that the LB is properly configured to route the HTTP traffic between the two OpenSSO servers, opensso1 and opensso2. Follow the single server configuration procedure and configure server opensso1.

This server is as follows:

http://opensso1.packt-services.net:8080/opensso. Now let us see how the

second server is configured.

[ 51 ]

OpenSSO Deployment and Configuration

Adding OpenSSO to an existing deployment

Once the first server is configured, you can access the configurator of the second server and proceed with the Create New Configuration option. Only this selection lets you configure the multi-server configuration. The first two steps will ask you the usual default user password (that is amadmin). You need to provide the amadmin password on your first instance (opensso1), because in the next step, configurator will use this user and password to internally log in to the http://opensso1. packt-services.net:8080/opensso to bring all the relevant details to perform a multi-server configuration. Once you select Add to Existing Deployment, at step three of the configurator, you will notice that configuration steps four and six are automatically disabled, that is because the first server already has this information, so it will not ask again.

The first step in the configuration is to provide the amadmin user's password that should match with the server opensso1. In step two certain values will be automatically filled (as shown in the preceding screenshot ), such as the Cookie Domain. Accept the default value. Note that the cookie domain value is matching with your server's DNS domain name. For this use case all the servers should reside in the same DNS domain name. In the later part of this book, we can learn how to SSO between hosts located on disparate DNS domains.

[ 52 ]

Chapter 2

During step three, you need to select the Add to Existing Deployment? to instruct the second server to share the (preceding screenshot) configuration of the previously configured OpenSSO server opensso1. At this point, you need to enter the URL of the first server. Configurator will use this information to bring the configuration data from the first server after authenticating as the top level administrator that you provided at configuration step one. Configurator will use the information obtained from the first server to set up the replication of the configuration store with the server being configured.

[ 53 ]

OpenSSO Deployment and Configuration

Configuration step five is the important one for the scenario we are working on. At this point you need to select Yes to configure the site with the load balancer. The site name could be any meaningful string but the Load Balancer URL must be a valid working HTTP load balancer URL. It should be entered with a domain-qualified host name along with the service port and deployment URI. In this case, it would be http://opensso-lb.packt-services.net:80/opensso. Now complete the configuration by selecting the appropriate option. You will see that the configurator will now set up the embedded store and will also set up the replication between opensso1 and opensso2. In the case of the external configuration store with Sun Java System Directory Server, it is the administrator's responsibility to set up the replication between directory servers. Log in to the administrative console. Browse to Configuration | Servers and Sites and click on http://opensso1.packt-services.net:8080/opensso. From this page, using the pull down menu (as shown in the following screenshot) under the Parent Site, select the site OpenSSO Multi-Server and save it. This configures the first server to also be a part of the site. At this point the LB will route the requests for both backend OpenSSO servers. You can view from the Servers and Sites page that now both servers will be part of the LB.

After adding the servers to the sites, log in as the top level admin user and click on to the Configuration | Servers and Sites tab of the console. Both of the servers will be listed under the site. The load balancer URL will be the primary service URL of the site, as shown in the following screenshot.

[ 54 ]

Chapter 2

Verification of multi-server deployment

Once the configuration is complete, you can verify the multi-server deployment by accessing the Load Balancer's URL. At this point we have not set up for session high availability, so only a request level failover will be provided by this deployment. This means that when you have already authenticated to opensso1 and if the opensso1 goes down, Load Balancer will automatically detect that failure and redirect the request to opensso2 (assuming it is up and servicing), but you will be asked to authenticate again because your session was lost when opensso1 went down. If the LB had not been there, you would have to wait until opensso1 came back. This causes service interruption for the service consumers, that is why service availability is critical in customer deployments. In order to test, first log in to the server using the load balancer URL (http://opensso-lb.packt-services.net:80/opensso/UI/Login), then bring down the server on which your session was created. This can be found out from the label server at the top left corner of the administrative console. When you access the authenticated session, it will show you the login page. This comes from the other OpenSSO server.

[ 55 ]

OpenSSO Deployment and Configuration

In a multi-server deployment case, you can find two or more bootstrap file locators in the home directory of the web container's runtime user. In this scenario, there are two OpenSSO servers configured on this host with "ssouser" as the runtime user. The naming convention for these files is unique and derived from the web application physical deployment directory with / (front slash) replaced with a _ (under score) and deployment URI with a prefix, AMConfig: [ssouser@opensso]:/export/ssouser/.openssocfg> ls AMConfig_export_ssouser_tomcat-8080_apache-tomcat-6.0.20_webapps_ opensso_ AMConfig_export_ssouser_tomcat-9090_apache-tomcat-6.0.20_webapps_ opensso_

Configuring using command line configurator

Quite often it is required to repeat the configuration and installation procedure to reproduce an issue or to apply the same configuration somewhere else. Typically, before deploying into production, customers run the products in a test environment. Here, upon achieving satisfactory functionality along with performance, they deploy it into production. In such cases, repeatability is the key to reproducing the same configuration in the production deployments. For OpenSSO configuration, this can be achieved by using the command line configurator which is a simple JAR file together with a silent installation file. This feature is exploited by the OpenSSO quality engineering team to automate the nightly builds configuration and execution of tests. The command line configurator can be found in the /opensso/tools/ ssoConfiguratorTools.zip.

Unzip this zip archive to get the configurator.jar. This includes the necessary Java classes to invoke the configurator using the silent configuration file. This file feeds the necessary OpenSSO configuration information to the CLI configurator: [ssouser@opensso]:/export/ssouser/.openssocfg> $JAVA_HOME/bin/java -jar ~/opensso/tools/configurator.jar -f /tmp/input.txt Checking configuration directory /export/ssouser/cli-config....Success. Installing OpenSSO configuration store...Success RSA/ECB/ OAEPWithSHA1AndMGF1Padding. Installing OpenSSO configuration store in /export/ssouser/cli-config/ opends...Success. Creating OpenSSO suffix...Success. Tag swapping schema files....Success. [ 56 ]

Chapter 2 Loading Schema opends_config_schema.ldif...Success. Loading Schema opends_user_schema.ldif...Success. Loading Schema opends_embinit.ldif...Success. Loading Schema opends_user_index.ldif...Success. Loading Schema opends_plugin.ldif...Success. ...Success. Reinitializing system properties....Done Configuring server instance....Done Creating demo user....Done Creating Web Service Security Agents....Done Setting up registration files....Done Configuration complete!

The silent configuration input file contains all the required information for the OpenSSO configuration. In this mode of configuration, it will not perform any error check like the browser-based configurator. The following is the data file /tmp/input.txt: SERVER_URL=http://opensso1.packt-services.net:8080 DEPLOYMENT_URI=/opensso BASE_DIR=/export/ssouser/cli-config locale=en_US PLATFORM_LOCALE=en_US AM_ENC_KEY=RandomOpenSSOEncryptionKeyValue ADMIN_PWD=secret12 AMLDAPUSERPASSWD=secret123 COOKIE_DOMAIN=.packt-services.net # #Config Store Details # DATA_STORE=embedded DIRECTORY_SSL=SIMPLE DIRECTORY_SERVER=opensso1.packt-services.net DIRECTORY_PORT=51389 ROOT_SUFFIX=dc=opensso,dc=packt-services,dc=net DS_DIRMGRDN=cn=directory manager DS_DIRMGRPASSWD=secret12 # # User Store Details # [ 57 ]

Download from Wow! eBook

OpenSSO Deployment and Configuration USERSTORE_TYPE= USERSTORE_SSL=SIMPLE USERSTORE_HOST=opensso1.packt-services.net USERSTORE_PORT=51389 USERSTORE_SUFFIX=dc=opensso,dc=packt-services,dc=net USERSTORE_MGRDN=cn=directory manager USERSTORE_PASSWD=secret12

This will create an embedded configuration store with user identity also pointing to the same configuration data store. It is equivalent to the default one click configuration option of the browser-based configurator.

Configuring OpenSSO with SSL/TLS

It is a straightforward process to configure the OpenSSO on a container that is already configured to run HTTP traffic over TLS/SSL. The browser-based configuration automatically picks up the right protocol if it has been accessed with HTTPS. For example, https://opensso.packt-services.net:8080/opensso/ config/options.htm. Here, there is no special setup required. Configurator automatically enables OpenSSO to start its services on the SSL/TLS listener. If you are using the command line configurator, then make sure that you load the root certificate of the certificate authority (that issued the server certificate of the container) into the trust store of the JVM that is being used to invoke the CLI configurator. If you are using the Java SDK as of the container, then this step is not required. This is useful if you want to configure an OpenSSO web application that is deployed on a remote server.

Configuring command line tools

OpenSSO provides few command line tools to automate administrative functions and to provide configuration data in bulk. One specific tool of our interest would be ssoadm. It is a Java class that is wrapped in a shell script on Unix systems and in a ssoadm.bat batch file on Microsoft Windows environments. The administrators can use this tool to automate their deployment configurations. This tool supports backup and restore of the OpenSSO configuration data and bulk federation. These features are not available from an administration console or in ssoadm.jsp. In order to configure the command line tools, the following prerequisites must be met: •

At least one OpenSSO server must be configured and running

•

CLI tools can only be configured local to the host where the OpenSSO is running [ 58 ]

Chapter 2

•

The runtime user of CLI tools must be the same as the OpenSSO configuration user

•

The version of the CLI tools zip (ssoAdminTools.zip) must match with the OpenSSO server version

If any one of the above prerequisites are not met, then the setup program will quit with an appropriate error message. During the configuration, the CLI setup script reads the bootstrap file from the OpenSSO configuration directory. Hence, the setup script must be invoked by the user name who configured the OpenSSO server. CLI tools are part of the ssoAdminTools.zip, which is present in the / opensso/tools directory. Unzip the tools into a directory. The setup script (setup. bat on Windows) is used to configure the CLI tools. To configure, just invoke the appropriate setup script, and all it needs to know is the bootstrap file location. The rest will be done automatically. The setup program will quit if the server mentioned in the bootstrap file is not available. However, it will try to look for the next entry in the bootstrap file if present. Here is a typical CLI tools setup session: ./setup -p /export/ssouser/opensso1-8080/ The scripts are properly setup under directory: /export/ssouser/opensso1-8080/ssoadm/opensso Debug directory is: /export/ssouser/opensso1-8080/ssoadm/debug. Log directory is: /export/ssouser/opensso1-8080/ssoadm/log. The version of this tools.zip is: Express Build 8a(2009-December-08 11:53) The version of your server instance is: Express Build 8a(2009-December-08 11:53)

Now the ssoadm tool has been set up properly, you can start using it. You need to provide the administrator's password in plain text in a file which is read-only for the user who invokes the tool: [ssouser@opensso]:/export/ssouser/opensso1-8080/ssoadm/opensso/bin> ./ ssoadm list-realms -u amadmin -f /tmp/.opensso.pass -e / Password file /tmp/.opensso.pass needs to be readonly by owner only. [ 59 ]

OpenSSO Deployment and Configuration [ssouser@opensso]:/export/ssouser/opensso1-8080/ssoadm/opensso/bin> chmod 400 /tmp/.opensso.pass [ssouser@opensso]:/export/ssouser/opensso1-8080/ssoadm/opensso/bin> ./ ssoadm list-realms -u amadmin -f /tmp/.opensso.pass -e / There were no realms.

In certain deployments the HTTP(s) traffic is usually one directional. That is, the traffic goes from one of the load balancers to the servers, but requests from servers are unable to reach the load balancers. In this scenario, ssoadm running on the OpenSSO server cannot reach LB, and hence will throw an error, which looks somewhat like the following: [ssouser@opensso]:/export/ssouser/opensso1-8080/ssoadm/opensso/bin> ./ ssoadm list-sites -u amadmin -f /tmp/.opensso.pass AdminTokenAction:

FATAL ERROR: Cannot obtain Application SSO token.

Check AMConfig.properties for the following properties com.sun.identity.agents.app.username com.iplanet.am.service.password

To get past this error, you can map the LB URL to the local OpenSSO server's naming URL by adding the JVM property: -D"com.iplanet.am.naming.map.site.to.server=http://opensso-lb.packtservices.net:80/opensso=http://opensso1.packt-services.net:8080/opensso"

in the ssoadm or ssoadm.bat script depending on your platform. In this scenario my ssoadm tool is configured to run on the opensso1 server. There are a few other command line tools installed as part this procedure including the following: • • •

ampassword amtune amverifyarchive

These tools will be explained later on in the context where they are applicable. While setting up with HTTPS/LDAPS you need to make sure the JVM that invokes the setup script does have the proper certificate authority's root certificate, otherwise you would see a "directory server not running" message.

[ 60 ]

Chapter 2

Uninstalling OpenSSO

Removing the OpenSSO server is a straightforward process, as all the configuration information is consolidated to one single place, except for the bootstrap locator file. Uninstalling the OpenSSO involves the following steps: •

Uninstall OpenSSO web application

•

Remove Configuration Directory from the file system

•

Remove the bootstrap locator file from the $HOME/.openssocfg directory of the web container's runtime user

This ensures that the server deployment and configurations are removed completely from the host, provided the configuration store was embedded. If your server was using an external configuration store, then you would need to physically remove the entries created by the OpenSSO. At this time there is no utility available in the OpenSSO to remove the LDAP entries that are created by the configurator, in the configuration store and identity store. In some versions of the Apache Tomcat server, you may be required to remove the directory under $CATALINA_HOME/work/Catalina/localhost which is named after your OpenSSO web application deployment URI. If it is not removed, you might see some weird behavior in the administrative console application in the subsequent deployment of OpenSSO in the same container instance.

OpenSSO release and support model

The OpenSSO product is being developed in a highly structured and processoriented development and test environment. There is a formal development and QA process being followed and strictly enforced by the management chain. All the new features and enhancements are diligently scrutinized for its relevance to the business, architectural correctness, and completeness. Active development of new features, enhancements and bug fixes are invariably happening every day on the OpenAM branch maintained by Forgerock. Oracle supports only the OpenSSO Enterprise 8.0 release and its updated releases for the customers who have a support contract with them. Forgerock has a subscription-based support model to service the customers who want to deploy the OpenAM as part of their access management solution. You can find the details on their support model documented at http://www.forgerock.com/subscriptions.html.

[ 61 ]

OpenSSO Deployment and Configuration

Summary

In this chapter, we have learned the basic environmental requirements for deploying the OpenSSO web application. We have seen how the product supports extensive configuration and customization features including a highly available system with a load balancer in front. OpenSSO provides both a browser-based configurator for the web-comfortable users and command line-based interfaces for the system administrators who are fond of doing things the command line way. The distinction of various release builds and the details presented in this chapter should give you an idea about which build to pick up for your specific use case. In the next chapter we are going to discuss the tips and tricks for the OpenSSO administration, including the browser-based user interface (UI) and a command line utility called ssoadm. I will also show you how one can create custom privileges and customizations on the UI console.

[ 62 ]

Administrating OpenSSO So, now you are ready to administrate the OpenSSO server that you have just configured. There is a pretty console provided by the server, to facilitate the configuration and identities administration in OpenSSO. At the time of writing, OpenSSO shipped with two different console interfaces. There are quite a number of new features planned and implemented in the Express Build 9 (even though the landscape for the OpenSSO open source project has changed significantly after Oracle acquired Sun Microsystems Inc.). I keep using the express builds for consistency. Entitlements provide fine-grained authorization as opposed to coarse-grained authorization. This is one of the key components in the express build 9. It is somewhat equivalent to Forgerock's OpenAM build 9; both were built from the same source tree. A new user interface (also referred to as new console) was built to manage the entitlements feature in OpenSSO. This console is relatively different from the default console that manages the rest of the features of OpenSSO. In this book, we will not be using the entitlements console. When I refer to console, it implies to the default console of OpenSSO. Both consoles are part of the OpenSSO web application's web archive file and are available out of the box after the product configuration. This chapter covers: •

Administration of OpenSSO using a web console

•

Using command line tools to administer OpenSSO configuration

•

Privileges mapping and assignment

•

OpenSSO console customization

Administrating OpenSSO

Administration interfaces

OpenSSO provides Graphical User Interface (GUI) as a separate web application to address specific customer deployment use cases. Well, GUI-based administration looks cool, but what about the command line interface to perform the administration activities? Yes, OpenSSO does provide a feature-rich command line tool too. In fact, there are certain administrative activities that can only be achieved by using the Command Line Tool (CLI) tool. I have briefly introduced this CLI tool called ssoadm in the previous chapter. Both the browser-based user interface and the CLI are widely documented and supported by Sun Microsystems Inc. with a valid support contract. There is one little, yet powerful, utility in terms of making some quick configuration changes in the server without even configuring the CLI tool. This tool is a stripped version of the CLI tool, ssoadm. This tool can be accessed by using the URL: ://servername:port//ssoadm.jsp. For instance, it would look something like http://opensso.packt-services.net:8080/opensso/ ssoadm.jsp. The ssoadm.jsp is not a supported tool. This tool facilitates the automation of multi-domain features such as the SAMLv2 protocol tests developed and executed by the OpenSSO quality engineering teams. This tool does not support all the subcommands provided by the CLI counterpart ssoadm or ssoadm.bat. So please use this version of the tool at your own discretion. Feature

ssoadm CLI

ssoadm.jsp

Setup and Configuration

Needs to be set up from the ssoAdminTools.zip

Available out-of-the-box upon product configuration.

Support

Thoroughly tested and supported by Sun Microsystems Inc., can raise escalations on this tool

Not a supported interface, so customers cannot raise escalations on this tool.

Limitations

All the sub commands are supported

Only selected sub commands are supported, features such as terminating a user session or exporting server configuration are not supported.

[ 64 ]

Chapter 3

In this chapter, you can find the procedures to administrate the server configuration as well as identities management. The OpenSSO console is not intended to replace a commercial grade Identity Management product such as Sun Identity Manager. Please refer to the appropriate documentation on how to integrate OpenSSO with Sun Identity Manager. The administrative interfaces are designed to manage the Authentication, Authorization, Entitlements, Web services security, and Federation and Audit configurations. Along the way, it also covers the basic identity CRUD (create, read, update, and delete) operations. In this chapter, you will be presented with browser-based configuration administration procedures along with its corresponding CLI procedures wherever applicable. After the product configuration you can log in to the administration console by using a valid OpenSSO user identity and password. Based on the authenticated identity's delegation privileges, the server will present the applicable user interface page. Broadly speaking, two user interface pages will be rendered—one for the administrator page, the other for normal non-administrator view.

Accessing the administrative console

The administrative console can be accessed via a supported browser such as Firefox, by entering the URL ://servername:port//console. It is possible to reach the console from the Login page entering the URL :// servername:port//UI/Login, but there is a key difference in the authentication process while accessing from the Login page and the console page. The administrator can configure different authentication chains for the administrative console that could be different from the normal user login. The server determines this based on the configuration set in the root realm of the OpenSSO server. You can find more on the authentication process and different types of authentication in the next chapter. In a typical deployment, the administrative console may be configured with a higher level of authentication. Users who access the administrative console have to authenticate multiple levels to get access to the administration page. This can be configured in the root realm, under (Access Control | Top Level Realm | Authentication) the Administrator Authentication Configuration as shown in the following screenshot. The Authentication Chain instance named as consleAccess is configured to authenticate using the LDAP authentication module, and will be invoked when the user accesses the ://servername:port//console. On the same page there is Organization Authentication Configuration that is configured with the normalAccess authentication chain that will be authenticating against a RADIUS server. When users access the Login page with the URL of the form ://servername:port//UI/Login, then the browser will redirect to the RADIUS authentication module. Generally, the administrative console will not be exposed to the end users of the OpenSSO server. [ 65 ]

Administrating OpenSSO

A realm is a unit that OpenSSO uses to organize configuration information. This should not be confused with the Java EE security realms.

In the out-of-the-box configuration, both administrator console and realm authentication configuration are set to be the same, so you will not notice any difference. Once you are authenticated as a valid user, OpenSSO is configured to redirect to the administrative console depending on the user type—whether administrator or non-administrator, and the respective page will be rendered.

Console views and privileges

For the top level administrator user, the console page would look like the one shown in following screenshot. This is the default console that is used to manage all the features except the entitlements.

[ 66 ]

Chapter 3

To access the entitlements management console, you can use the URL of the form ://servername:port//admin. After being authenticated as the top level administrator user amadmin, you can view the console as shown in the following screenshot:

[ 67 ]

Administrating OpenSSO

Administrative users get different views based on their access privileges. Multiple levels of privileges can be set to an identity which we will see in a short while. Now let us look at how the normal (non-administrator) user console appears in the browser. Normal users access the login page specific to the realm where they belong. If the login page is accessed with no URL query parameters (these parameters are detailed in the next chapter), then the server assumes the root (/) realm for authentication and other purposes. As you are aware, OpenSSO comes with a default user demo with no administrative privileges. We can use this user to demonstrate the console page for the end users. Access the login page of the server :// servername:port//UI/Login?realm=/. Remember the query parameter ?realm=/ is optional for the root realm, whereas for the sub realms under the root, you need to specifically supply this query parameter to address that particular realm. Anyway, on the login prompt, enter demo as the user and changeit as password. All this is with the assumption that you have the default OpenSSO configuration as described in Chapter 2, in the OpenSSO one click configuration section. Upon successful authentication, the resulting page would appear something like the one shown in the following screenshot:

[ 68 ]

Chapter 3

Note that there is no tabbed console for the non-administrator users such as the demo user. Tabbed pages will appear only if the authenticated user has one or more administrative privileges. These privileges can be applied to a user identity through a role or group. Authenticated identities inherit the privilege by inheriting the specified role or group to which a privilege is assigned. An administrator logged into the administrative console can manage the system configuration based on the privileges assigned to the user. For example, a policy administrator can only manage the policies and the Policy Service configuration. This person cannot manage the authentication service or the identities under the subject tab. The console itself hides those views from the Policy Administrator. When both the realm and Policy Administrator privileges are assigned, the effective privilege of this user would be the aggregation of both administrative privileges. Let us defer certain administrative operations to a later chapter as it would be easier to understand them at a later stage. The goal of this chapter is to introduce the console, and how to navigate through the console features.

Console landing page–common tasks

As soon as the users log in to the console, they will be presented with an administrative user interface or a normal user interface based on the effective privilege. In the administrator login case, upon successful authentication a default landing page will be rendered. This page includes all the workflow wizard - like tasks that can be invoked to configure certain OpenSSO configuration steps. These work-flows are spread across both new and old consoles. At the time of writing, the following workflows were available from the default landing page: •

Configuration of SAMLv2-based Identity Provider and Service Provider configurations

•

Integration of OpenSSO with Google Apps

•

Integration of OpenSSO with Salesforce

•

Creation of Fedlet

•

Testing federation connectivity

We will revisit some of these workflows in the later chapters. There are many easy-to-configure tasks rendered like a workflow wizard for the security token service. WebEx integration with OpenSSO is available from the entitlements management console.

[ 69 ]

Administrating OpenSSO

Access control tab

In OpenSSO a realm is a collection of configuration information that solves a specific business use case. A realm can be envisaged as a unit that OpenSSO uses to organize configuration information. Authentication properties, authorization policies, data stores, identities, and other services such as session service data can be defined within the realm. Typically a realm includes the following type of information: •

One or more data store's configurations to store identities' data.

•

List of authentication types and modes supported by the realm. An OpenSSO server can support any number of authentication types, the realm configuration enables only specific authentication modules. By default, not all the authentication types are available to the end user.

•

Policy information that will be used to determine which resources are protected by OpenSSO and which identities can access what.

•

Delegation privileges that are available.

•

Administration data for realm management.

•

Web Service Clients and agents configuration.

When the server is configured, the top level realm called root realm is created. Root realm is denoted using / (front slash). Any subsequent realms created under root (/) are called sub realms. These are addressed in a Unix - like directory naming convention. For example /sales/support is representing third level sub realm sales created under support which is a sub realm of the top level root realm. From the console it can be viewed from the Access Control tab. A new realm can be created from this page as well.

[ 70 ]

Chapter 3

To manage a specific realm, select the realm by clicking on the realm name. It will bring up another tabbed page containing the following sub tabbed pages:

You will find eight tabs. Each lets you edit specific configurations for the selected realm. The CLI tool ssoadm also offers create-realm, list-realms, delete-realm sub commands to manage the realms though the command line interface.

General

Realm-specific properties such as the DNS alias names can be set from this page. These values are used in the authentication process and while evaluating policies with dynamic realm aliases enabled. It is possible to set a realm as inactive from this page, so that the identities from that realm cannot perform any authentication and authorization activities.

Authentication

Authentication is the process of determining if an application or identity is actually what it claims to be. In OpenSSO, there are multiple ways to achieve this using various industry standard authentication types and protocols. The administrative console provides ways to define multiple levels of authentication by leveraging the authentication chain feature. From this tab the administrator should be able to configure the account lockout feature, post authentication plugin customization. If profile data is required for an authenticated identity to obtain a Single SignOn token, it can also be configured from this location. OpenSSO requires a valid authenticated user to perform any modification action on its configuration data. A user profile or profile is a collection of user identity attributes stored in the underlying identity store. Typically, the authorization for protected resources is carried out based on these user profile attribute values. Chapter 4 takes us deep into authentication and session service, including the options for managing the authentication configuration, using the command line interface.

[ 71 ]

Administrating OpenSSO

Service

In the OpenSSO server, a set of related attributes are defined as a service. It is an XML document formulated according to the document type definition provided by the OpenSSO sms.dtd. This DTD can be located in the amserver.jar or in the WEB-INF directory of the OpenSSO web application archive. Each feature in the OpenSSO is exposed as a service that has a well-defined XML schema. These schema files will be added to the configuration store when the server is configured. For your reference, the XML files are available under the OpenSSO configuration directory in the file system. To create new services, the service developer should create a new service schema by following the syntax dictated by sms.dtd. Services can be defined as Global, Realm, and User level. This granularity makes the service flexible to be inherited at different levels, if one is not defined at the current level. Only certain services are assignable at different levels. For example, the global services provide one single service value that is common across the server, irrespective of the realm that the user belongs to. The OpenSSO logging service is one such global service. Typically four possible levels are available in the server: User, Role, Realm, and Global. Global services are automatically added, and they cannot be manually added or removed from the console. Services with realm and user-level attributes can be added to and removed from a user or realm. The Service tab helps to add or remove the realm-based services. If there is no service added to a realm, then the service values are inherited from the global configuration and not from any peer or sub realm configuration (refer to following diagram). Role-level services are available only with Access Manager Repository data store configuration.

To add new services to a realm just click on the Add button. All the existing realm-level services that are available to be added will show up as a selectable radio button, and you can add one service at a time as shown in following screenshot:

[ 72 ]

Chapter 3

It is also possible to manage the services from the ssoadm command. For instance, the following sequence of commands assign, update, and remove the Session service for the root realm: ./ssoadm add-svc-realm -u amadmin -f /tmp/.passwd_of_amadmin -e / -s iPlanetAMSessionService -a iplanet-am-session-quota-limit=5 iplanet-amsession-max-session-time=1200 iplanet-am-session-max-caching-time=3 ./ssoadm set-realm-svc-attrs -u amadmin -f /tmp/.passwd_of_amadmin -e / -s iPlanetAMSessionService -a iplanet-am-session-quota-limit=5 iplanetam-session-max-session-time=189 iplanet-am-session-max-caching-time=30 ./ssoadm remove-svc-realm -e / -u amadmin -f /tmp/.passwd_of_amadmin -s iPlanetAMSessionService

Data stores

Data stores refer to the identity repository store, where a realm stores all of its identity subjects including the user, role, and group information. A realm can have more than one data store. Each realm should have at least one data store configured to store and retrieve the identity information for that realm. Out-of-thebox OpenSSO can be configured to use five different LDAP servers including the Oracle Directory Server Enterprise Edition. There is also a MySQL-based identity repository implementation which is available as an early access feature. Before using the LDAP-based identity repository data stores in OpenSSO, customers should have the respective LDAP server in their environment configured. A supported data repository can be created by just providing the LDAP server host name, port, and a distinguished name associated with a password. Creating these stores adds the OpenSSO identity schema to the directory server and makes some configuration changes to tune the indexes.

[ 73 ]

Download from Wow! eBook

Administrating OpenSSO

Chapter 8 is devoted to the identity data stores and their management, and you can find more details on how to create various types of user stores and manage them.

Privileges

OpenSSO allows the users to have different levels of privileges so the administration activities can be delegated to more than one person to ease the administration duties. In fact it is a requirement in some business cases where each realm (in an ISP scenario) must be administrated by a different administrator. This can be achieved by using the default privileges provided by OpenSSO. The privileges are assigned to the end user identity by means of a role or group membership. In simple terms a privilege is an action that can be performed on a resource; for example, a READ operation on a log. Privileges can be dynamically assigned to users deemed administrators by creating a group or role, assigning to it the appropriate privilege, and adding the specific user as a member of the group or role. The default privileges that are available in a default OpenSSO (as shown in the following screenshot) server configuration covers most use cases. It is also possible to create more custom privileges. Refer to the OpenSSO customization guide for more details on this. A write privilege subsumes update and delete access rights as well.

[ 74 ]

Chapter 3

With reference to the preceding screenshot, let us see what are these privileges are: •

Read and write access to all configured Agents (AgentAdmin): Identities that inherit this privilege can read, write, delete, and update the agent identities configuration including the web services, STS agent profiles, and agents groups. Users with this privilege cannot create a policy or an identity.

•

Read and write access to all log files (LogAdmin): Users who acquire this effective privilege are allowed to read and write to the OpenSSO logging, irrespective of the logging repository.

•

Read and write access to all realm and policy properties (RealmAdmin): It is a privilege which provides a realm-level administration capability including policy, service, data store, agents, and identities create and delete rights. When logged on to the console, only the Access Control tab will be shown. The rest of the tabs will not appear.

•

Read and write access to all federation metadata configurations (FederationAdmin): As it says from the description, users with this privilege can only manipulate the metadata information of the federation protocols such as SAMLv2. Administrators with this privilege cannot create a realm or any kind of identity entity.

•

Read and write access only for policy properties (PolicyAdmin): Users with this privilege can only read and write to policy configuration and policies themselves. When logged on to the console, only the Access Control tab will be shown and the rest of the tabs will not appear.

•

Read access to all log files (LogRead): It provides read access only to all the log records of the OpenSSO server. This will ensure that the log administrators can only read the data and cannot tamper with access log records.

•

Write access to all log files (LogWrite): This privilege provides only write access (no read access) to the OpenSSO logging repository. You may wonder why provide read access. The remote clients of OpenSSO are only required to remotely log the entries. There is no reason for those clients to read the log records that is why no read access is required for those remote clients.

•

REST calls for Policy evaluation (PrivilegeRestAccess): A privilege that allows the clients to perform Policy Evaluation by making REST calls.

•

REST calls for managing entitlements (PrivilegeRestAccess): Identities with this privilege can manage (read and write) the entitlements defined in the OpenSSO server.

•

REST calls for searching entitlements (PrivilegeRestReadAccess): Identities with this privilege can only read and search the entitlements defined in the OpenSSO server. [ 75 ]

Administrating OpenSSO

All these privileges can be assigned to user identities by means of associating the user identities with a corresponding group or a role (a role is supported only with the Sun Java Enterprise System Directory Server). It is wise to use group for its wide support by all of the data repositories. From the administrative console, a top level administrator or a realm administrator can perform the assignment of these privileges. This process is self-explanatory from the console. The text in brackets mentioned in the preceding list are to be used when you invoke ssoadm to add or remove privileges. There is an example included in this section that explains how ssoadm can be used to assign privileges. When multiple privileges are assigned to an identity, the effective access rights would be the aggregation of all of the assigned privileges. For instance, if a group has both PolicyAdmin and RealmAdmin privileges, then the effective privilege of the user who is a member of this group would be a realm administrator. The use case here is to create a user identity who can perform the Policy Administrator activities. To make this happen, carry out the following simple steps: 1. Create the user identity jdoe: ./ssoadm create-identity -u amadmin -f /tmp/.passwd_of_amadmin -i jdoe -t User -a cn=JohnDoe sn=Doe userpassword=secret123 -e /

2. Create a group called Policy Administrator: ./ssoadm create-identity -u amadmin -f /tmp/.passwd_of_amadmin -i "Policy Administrator" -t Group -e /

3. Assign the PolicyAdmin privilege to the group Policy Administrator: ./ssoadm add-privileges -u amadmin -f /tmp/.passwd_of_amadmin -e / -i "Policy Administrator" -t Group -g PolicyAdmin

4. Add the user jdoe as the member of the group Policy Administrator: ./ssoadm add-member -u amadmin -f /tmp/.passwd_of_amadmin -m jdoe -y User -i "Policy Administrator" -t Group -e /

That is it, now user jdoe can log in and perform the activities of a Policy Administrator. In the same manner, privileges can be removed from the group by using the remove-privileges subcommand. Multiple privileges can be added or removed by separating them with a white space after the -g command option.

[ 76 ]

Chapter 3

Policies

Access Management is one of the core services provided by the OpenSSO server. Policies play a key role in making this happen. Access to resources are controlled by means of defining proper policies for the resources managed by the OpenSSO server. In Chapter 6, policies and authorization will be dealt with at length. Let us focus on. Let us focus on the management of policies in this section. Like any other configuration, policies can also be managed using the ssoadm command line tool. There are two types of policies that can be created using the OpenSSO Policy Service, normal policy (or simply policy), and referral policy. A normal policy controls access to a protected resource and consists of rules, subjects, conditions, and response provider's values. Whereas a referral policy delegates policy creation and evaluation to another realm. Like, the normal polices, referral policies can have one or more subjects, conditions, and response providers. Typically a policy irrespective of its type should have a rule and subject defined in order to be applicable to an identity. A referral policy must be defined in the parent realm in order to create a policy in the sub realm. Each realm should add the Policy Service to configure specific types of conditions, subjects, and response providers. If there is no Policy Service defined for the realm, then the values will be inherited from the global Policy Service configuration. From the console you can create policies by clicking on the specific type of the policy. To create policies from the ssoadm tool, you need to supply the policy definition in a well-formed XML document defined according to policyAdmin.dtd. This can be found in amservices.jar as well as in the WEB-INF directory of the OpenSSO web application archive. The easiest way to create policies from a command line is to create the policy from the console and then export it as an XML document. Once you have this XML document, it can be customized to meet your requirements. It may be possible to create a template so you can use it for bulk loading of policies by just changing the resource names and subjects. A simple policy exported using the ssoadm command looks like this: ./ssoadm list-policies -u amadmin -f /tmp/.passwd_of_amadmin -p "test policy" -e / OR from command line



[ 77 ]

Administrating OpenSSO

deny allow id=jsmith,ou=user ,dc=opensso,dc=java,dc=net (objectcla ss=*)

The resource name, subject, and condition highlighted in the XML file, referralPolicy="false" indicates it is a normal policy. According to this policy, OpenSSO will send an allow decision for GET action and deny for POST action when the authenticated user's principal matches with jsmith, and the LDAP filter yields the distinguished name of the principal matched in the subject (that is, jsmith). To create a policy from ssoadm, create the definition of the policy in the XML format and use the subcommand create-policies: ./ssoadm create-policies -u amadmin -f /tmp/.passwd_of_amadmin -e / -X / tmp/policy.def.xml [ 78 ]

Chapter 3

Any kind of policy can be created in this way. To update the policies using the command line, export the concerned policy, edit it in the XML document, and delete and add the updated policy back to the system. To delete use the sub command delete-policies, for example to delete the policy named test policy, invoke the ssoadm with subcommand delete-policies: ./ssoadm delete-policies -u amadmin -f /tmp/.passwd_of_amadmin -e / --policynames "test policy"

Subjects

The Subjects interface enables basic identity management within a realm. In the console any change initiated from this tab will not impact the configuration store, because all the identities that are managed from this place are stored in the identity store that you have created during the configuration of OpenSSO or after configuration. One exception you should be aware of here is that of agents identity. Agents are stored in the configuration store even though they appear as part of the subjects. Agents are clubbed with other identities for their logical relevance, and historically (in the Sun Access Manager days) agents were stored as part of the user identity store. Depending on the type of identity store you would be presented with different interfaces when you access the Subjects tab. Filtered Role and Role tabs will be visible only if you have created an identity store of type Sun DS with OpenSSO or Access Manager Repository. These tabs will not be present for the other type of identity data stores. With the Sun Java Enterprise System Directory Server, you will receive the display as shown in the following screenshot for the Subjects tab:

[ 79 ]

Administrating OpenSSO

For all other identity data store types the Subjects tab view will be same, as shown in the following screenshot:

As you can see in the preceding screenshot, the Role and Filtered Role tabs are not available for other data stores, because those LDAP servers do not have the role entity concept. This is due to the fact that it is not a part of the LDAPv3 specification. Creating and managing the subjects from the console is a pretty straightforward task. In the next few sub sections let us see how to create and manage the users, roles, and groups using the ssoadm command line tool.

Managing users from the command line tool

Let us quickly see how the ssoadm command line tool can be used to perform the CRUD operation for the identity objects. Following set of ssoadm sub commands represent the user identity CRUD (create, list, update, read, and delete) operations. Certain non-essential messages emitted by the ssoadm tool have been removed for brevity. All these examples operate on the root realm, you can replace / with any realm of your interest. The intent here is to introduce these sub commands to you and not to explore every possible option of these commands: ./ssoadm create-identity -i bjensen -t User -u amadmin -f /tmp/.passwd_ of_amadmin -a cn=Ben.Jenson sn=Jenson userpassword=secret123 -e / ./ssoadm list-identities -u amadmin -f /tmp/.passwd_of_amadmin -e / -t User -x "bj*" ./ssoadm set-identity-attrs -i bjensen -t User -u amadmin -f /tmp/. passwd_of_amadmin -a cn=MyBenson telephonenumber=408-276-5044 -e / ./ssoadm get-identity -i bjensen -t User -u amadmin -f /tmp/.passwd_of_ amadmin -e / ./ssoadm delete-identities -u amadmin -f /tmp/.passwd_of_amadmin -t User -i bjensen -e / [ 80 ]

Chapter 3

Managing groups from a command line tool

In the same manner as of the user identities, groups can also be managed from the ssoadm tool. Let us continue from the user identity example described in the Managing users from command line tool section. Now we want to create a new group called Administrator and add the user bjensen as a member of this new group. After that the group will be removed from the system. When the group is removed, the underlying directory server's referential integrity feature automatically removes the memberships from the respective user entries if applicable: •

Creating a group named Administrator at the root realm: ./ssoadm create-identity -i Administrator -t Group -u amadmin -f / tmp/.passwd_of_amadmin -e /

•

Listing all the groups that start with string ad in the root realm: ./ssoadm list-identities amadmin -e / -x "ad*"

•

-t Group -u amadmin -f /tmp/.passwd_of_

This command adds user bjensen as a member of the group Administrator (you need to make sure the user bjensen is already created in the user store): ./ssoadm add-member -m bjensen -y User -i Administrator -t Group -u amadmin -f /tmp/.passwd_of_amadmin -e /

•

To display the attributes of the group Administrator, use the get-identity sub command: ./ssoadm get-identity -i Administrator -t Group -u amadmin -f / tmp/.passwd_of_amadmin -e /

•

To delete the group identity, use the delete-identities sub command: ./ssoadm delete-identities -u amadmin -f /tmp/.passwd_of_amadmin -t Group -i Administrator -e /

To manage the roles using the command line, use the above sub commands with identity type Role. Just supply Role for the -t options.

Agents

In OpenSSO terminology, an agent could represent any of the supported Policy Enforcement Points (such as Java or Web Server agents) profiles, the web service, or Security Token Service client profiles. In order to configure any of these agents, a profile that represents the properties of the specific agent must be created using this interface. All the OpenSSO policy agents 3.0 configurations are centralized in the OpenSSO configuration store, as opposed to the local flat file configuration. To maintain the compatibility, local file-based configuration is still supported by OpenSSO policy agents. [ 81 ]

Administrating OpenSSO

There are different types of agent profiles, as shown in the following screenshot. They can be created using this interface. An in-depth coverage of these profiles is beyond the scope of this book. You need to be aware of the fact that the configurations of the agents is stored as part of the OpenSSO configuration store. Any changes to these agents' profiles are instantly communicated to the clients. These instant notifications make most of the agent profile properties hot swappable. If this feature had not been there, any profile change would have required agent application container restart.

Agent authenticator agentAuth is a default profile that will be available in the freshly configured OpenSSO server. The password for this profile will be the same as that of UrlAccessAgent, which you have provided at the time of the server configuration. This profile can be used as the application user when your client application needs to read the properties of more than one agent profile. There are three profiles wsc, wsp, and SecurityTokenService created and added to the agentAuth profile in a typical server configuration. Agent profiles can be created from the ssoadm command line tool as well. You can find the types of agents supported by your server using the show-agent-types sub command. To create a Java agent profile from the command line, invoke: ./ssoadm create-agent -u amadmin -f /tmp/.passwd_of_amadmin -s http:// opensso.packt-services.net:8080/opensso -g http://paycheck.packtservices.net:4343/agentapp -t J2EEAgent -a userpassword=agentsecret -e / -b paycheck

[ 82 ]

Chapter 3

This will create a Java agent profile at the root realm with the name paycheck on the OpenSSO server running at the URL http://opensso.packt-services.net:8080/ opensso and the paycheck application is deployed on http://paycheck.packtservices.net:4343. To verify the agent profile, you can try to authenticate to the OpenSSO server with the profile you just created. Use the login URL of the OpenSSO with the query parameter ?module=Applicatio n&IDToken0=paycheck&IDToken1=agentsecret. After a successful authentication,

you will be shown the properties of the agent profile. For example, to verify the profile paycheck, use http://opensso.packt-services.net:8080/opensso/UI/ Login?module=Application&IDToken0=paycheck&IDToken1=agentsecret.

Configuration

So far all the configurations that we dealt with are specific to a realm. There are some global services and properties available in the OpenSSO server that are configurable by the administrator. Any changes in these global properties affect the whole server. Hence any global change has to be carefully planned and executed. This tab in the console is accessible only to top level and realm administrators. As you can see from the console, Authentication, Console, System, Global, and Servers and Sites are available. In the previous section, you have been introduced to the services and the inheritance of service attribute values from the next level. If no services are defined at the current level where the attribute value is being requested, then the value for that service will be fetched from the global area, if that service has defined a global value. Such global values can be defined using this Configuration tab. There are certain properties that can only be defined at the global level, such as enabling the session quota and setting monitoring service ports. The part that is of our interest would be Servers and Sites. If you are familiar with the predecessor of OpenSSO that is the Sun Java System Access Manager, it stored most of its configuration properties in a file named AMConfig.properties. In the multiple server deployment scenario, each server contains its own AMConfig.properties. If a value in the file has to be modified, then that change has to happen in all of the Access Manager servers. Evidently, it is a painful error-prone task to perform on all servers. One of the major improvements in OpenSSO is eliminating the AMConfig. properties by consolidating all the configurations into a centralized configuration store. Over 200 properties are consolidated and appropriately categorized under this tab in the administrative console. Many of the properties are hot swappable, which means any change in these properties will be automatically pushed to the servers that share this centralized configuration store. In an external configuration store case, a persistent search thread runs to propagate the changes to the OpenSSO.

[ 83 ]

Administrating OpenSSO

To learn more about the properties which are hot swappable, read the OpenSSO Administration Guide. Certain properties show up as non-editable labels. If you want to provide different values for these properties, click on the Inheritance Settings that you see in the following screenshot. Uncheck the property that you want to make editable on the server configuration page.

All right, let us get back to our ssoadm way of configuring the OpenSSO server properties. Even though the console shows different tabs, General, Security, Session, SDK, Directory Configuration, and Advanced, internally all these properties are stored under one single node. It is a very simple process to read, update, and delete the values using the command line interface tool ssoadm.

Retrieving all the server properties

All the server instance properties can be retrieved by using the sub command listserver-cfg, invoking this with the corresponding server instance will dump all the properties that you configure through the console: ./ssoadm list-server-cfg -u amadmin -f /tmp/.passwd_of_amadmin --servername http://opensso.packt-services.net:8080/opensso

The preceding command returns all the properties set for the instance http:// opensso.packt-services.net:8080/opensso with the exception of the inherited values from the default configuration. To include the inherited value in the output, use the -w option along with the preceding command.

Updating server configuration properties

In the same manner ssoadm can be used to update the property value of any OpenSSO server instance. All you need to know is the property name that can be obtained by executing the list-server-cfg subcommand. If you do not see the property name, use the -w option to obtain all the property names. In the following example, the SMTP server name and port are being updated for the server instance http://opensso.packt-services.net:8080/opensso: ./ssoadm update-server-cfg --servername http://opensso.packt-services. net:8080/opensso -u amadmin -f /tmp/.passwd_of_amadmin -a com.iplanet. am.smtphost=mailhost.packt-services.net com.iplanet.am.smtpport=25 [ 84 ]

Chapter 3

Note that there is a white space between the properties provided for the -a option. If you want to update multiple properties for a server instance use the -D option that takes a text file as input where each line is a property value pair.

Removing properties from server configuration

There may be a requirement to add some custom properties that are not already in the default configuration. These properties will be added using the Advanced tab from the console. For some reason, if this property needs to be removed, you can accomplish that by using remove-server-cfg subcommand. For instance, the following command removes the property opensso.protocol.handler.pkgs from the server instance http://opensso.packt-services.net:8080/opensso: ./ssoadm remove-server-cfg -u amadmin -f /tmp/.passwd_of_amadmin -s http://opensso.packt-services.net:8080/opensso -a opensso.protocol. handler.pkgs

Sessions tab

This interface from the console is available only to the top level and root realm administrator. All the sessions across the site can be managed from here. It provides information about the active sessions on specific servers. The administrator can select the server from the pull down on the top right corner to view the sessions count hosted by that server. In the default configuration, an administrator is configured to view only 120 sessions. This value is set to minimize the resources required to display the sessions on the browser. It is likely that the browser will run out of memory if you try to display a large number of sessions from the server. You can use the filter that is located with a search button on the left side of the page to restrict to particular identities' sessions. To terminate a particular user's session, type the username in the search filter area. If there is a session for that user, then it will be displayed. Select the user session and click on Invalidate Session. Instantly, the session will be destroyed and notifications will be sent to clients who had registered for notifications.

[ 85 ]

Administrating OpenSSO

Managing sessions using ssoadm

The OpenSSO sessions can also be managed using the ssoadm tool. To list the sessions on a server, list-sessions subcommand can be invoked. Note that the ssoadm.jsp will not support this option. To terminate a session, just enter the index number associated with the user sessions. You can also list the sessions based on the filter using the -x option. A filter -x "sam*" would yield all the sessions which principally start with the string sam. There is also an option that will be useful to count the number of sessions the session table subsumes. The -q command line option can be used to list the sessions. When this option is supplied, the ssoadm tool will not enter into the interactive mode. Together with this option, the administrator can script to list the number of sessions in the server to monitor server load. Remember to tune the property in the global session service that allows only 120 sessions by default to be displayed on the console or ssoadm tool: ./ssoadm list-sessions -u amadmin -f /tmp/.passwd_of_amadmin -t http:// opensso.packt-services.net:8080/opensso -x "sam*"

Customizing the console

In production-level deployments, often it is required to customize the product to adapt to the organization's specifications, its look and feel, and business logo, among other things. OpenSSO does offer console customization flexibilities to enable customers to have their own look and feel. There are a lot of documentations about the Login page customizations available in the OpenSSO public documents. So it does not add any value to duplicate those instructions here. Rather, let us focus on how one can extend the user identity schema (which is stored in a supported LDAP server, to add more attributes the LDAP schema must be extended) to add more attributes to the users, which are created and managed from the OpenSSO console. Once you customize the user schema, all users created by the OpenSSO interfaces including the CLI and administrative console would use the custom schema. As part of this process, you will be able learn how the end user profile page can have more attributes upon logging into the server. In the default configuration, the server does support extensive user attributes that are part of the inetorgperson LDAP object class. It should address most of the business use cases. However, it may be required to add some legacy attributes as part of the user object. To make this happen OpenSSO user schema must be customized. In order to customize the user schema follow these simple steps: •

Design and extend the LDAP schema

•

Extend the OpenSSO user schema

•

Verify the customizations [ 86 ]

Chapter 3

Let us explore these topics in detail in a short while. The attributes, object classes, and schema Object Identifiers (OID) used in this section are for example illustration purposes only. You need to obtain proper OIDs for your own organization, if you want to customize your schema.

Extending LDAP schema

For the sake of simplicity let us assume that three attributes packt-servicesuserstatus, packt-services-user -location, and packt-services-userblog are defined using a single object class named packt-services-user-class. The deployment use case that we are trying to achieve here is to make all of the three attributes mentioned above editable for the administrative users and make packtservices-user -location, and packt-services-userblog attributes editable by the non-admin users. In this example, OpenDS is used as the user store that stores all the user identity information. The first part of the customization is to extend the LDAP schema as these attributes are not part of the generic LDAP schema. The following listing contains the LDAP schema definition that can be added to the OpenDS server by using the ldapmodify utility. For readability the lines are folded, so when you cut and paste, make sure the lines that start with attributeTypes: and objectclasses: are not folded: dn: cn=schema changetype: modify add: attributeTypes attributeTypes: ( 1.2.840.113556.1.2.192 NAME 'packt-services-userlocation' DES C 'Packt Services User Service Location ' SYNTAX 1.3.6.1.4.1.1466.115.121.1.12 X -ORIGIN 'OpenSSO Packt Services Deployment' ) attributeTypes: ( 2.16.840.1.113730.3.1.602 NAME 'packt-services-userstatus' DE SC '"active", "inactive" status of a user' EQUALITY caseIgnoreMatch SINGLE-VALUE SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 X-ORIGIN 'OpenSSO Packt Services Deployment ' ) attributeTypes: ( 2.16.840.1.113730.3.1.603 NAME 'packt-services-userblog' DESC 'A users blog Web addresses' SYNTAX 1.3.6.1.4.1.1466.115.121.1.26 X-ORIGIN 'Ope nSSO Packt Services Deployment ' ) add: objectClasses objectClasses: ( 1.3.6.1.4.1.42.2.27.9.2.96 NAME 'packt-services-userclass' DES [ 87 ]

Download from Wow! eBook

Administrating OpenSSO C 'Packt Services user object class' SUP top AUXILIARY MAY ( packtservices-use r-location $ packt-services-user-status $ packt-services-user-blog) X-ORIGIN 'Op enSSO Packt Services Deployment' )

If you have loaded the schema to OpenDS, then it is ready to store the new attributes that we are planning to use in the OpenSSO user schema. At this point we can proceed to the next section to extend the User Service.

Customizing OpenSSO User Service

All the OpenSSO services are defined using the XML services schema that conforms with sms.dtd. Any changes that you would like to make in the services should be made in the service schema. All the services schema are stored in the configuration store of the server as an XML blob. The original XML schema files are stored in the file system under the configuration directory of the OpenSSO server. You can locate them under /config/xml. To extend the user schema defined using the service name iPlanetAMUserService (amUser.xml) carry out the following sequence of steps: •

Add the custom attributes to amUser.xml

•

Remove User Service schema from the configuration store

•

Add extended User Service schema

•

Add the label names for the new properties

•

Update the privileges

•

Restart and test the OpenSSO server

Adding attributes to amUser.xml

Before editing the /config/xml/amUser.xml file make sure you make a copy of this original file. In case you mess up the customization process you can revert back to the original configuration using this original schema file. Using your favorite editor add packt-services-user-status, packt-services-userlocation, and packt-services-user-blog attributes at the end of the file just before the element. You will notice in the following code listing here that there are some attribute schema element properties that need to be defined for each attribute schema. These properties determine what kind of values an attribute can accept, whether to display for the end user and a value can be null for that attribute.

[ 88 ]

Chapter 3

The following code must be compliant with the jar://com/sun/identity/sm/sms. dtd. Make sure you appropriately close the tags to arrive at a well-formed

XML document:

Active Inactive Inactive

Removing User Service schema

Updating the XML schema file alone is not sufficient to make the new attributes a part of the OpenSSO User Service. At this point the OpenSSO server still uses the old schema that exists in the configuration store. Unless the configuration store is updated with the new values, your custom attributes will not show up in the console. So the existing service schema must be removed first. It can be removed by using the ssoadm.jsp or ssoadm CLI tool. There is no provision in the administrative console to remove the service. You can use the delete-svc subcommand to remove any existing service from the server. Invoke the following command to remove the User Service: ./ssoadm delete-svc -s iPlanetAMUserService -u amadmin -f /tmp/.passwd_ of_amadmin

This will remove the existing User Service schema from the server. [ 89 ]

Administrating OpenSSO

Adding the updated User Service schema

The updated user schema must be loaded now. It can be accomplished by using the create-svc sub command of the ssoadm utility. To add the updated User Service schema that contains the custom attributes, execute the updated user schema file. It is located in /export/ssouser/opensso/config/xml/amUser.xml file. This process will update the configuration store with that latest schema for the User Service. In the multiple OpenSSO servers that share the same replicated configuration, you just perform the above step once. There is no need to execute in all of the servers as the configuration information is automatically replicated to all the servers. Here is an example: ./ssoadm create-svc -X /export/ssouser/opensso/config/xml/amUser.xml -u amadmin -f /tmp/.passwd_of_amadmin

Adding the labels

The new attributes that have been added to the User Service require a human readable label to be shown in the console. This label is a localizable string (i18nKey) which is stored in a property file stored as part of the OpenSSO web application. This property file name is amUser_locale.properties where locale is the current localized environment. For the English locale, it would be amUser_en.properties. An appropriate label should be added for each property that is added to the amUser. xml. If the value is empty then that attribute will not be displayed on the console. It is very important to match the i18nKey values that you supplied in the amUser.xml. For instance, the following screenshot has the i18nKey property. cust101 value is supplied for the property packt-services-user-location, so you should supply a meaningful string that will relate to this property. In this case, it is aptly labeled as Packt Services User Location. This file can be located under the WEB-INF/classes directory. Some of the application servers may not let you modify directly under the web application deployment directory. In such scenarios, you can generate a new opensso.war after making the customizations: cust100=Packt Services User Status cust101=Packt Services User Location cust102=Packt Services User Blog Entry cust200=Status Active cust201=Status Inactive

[ 90 ]

Chapter 3

Adding the custom attributes to data store configurations

Even though the user schema is updated with latest schema changes, the custom user attributes will not be available to the newly created users until the custom attributes and object classes are added to the specific realm's data store configuration properties as shown in the following screenshot. You need to manually edit the existing data store configuration properties. This will instruct the IdRepo sub system that the new attributes need to be added whenever a new user is created or their attributes are to be retrieved along with these custom attributes.

[ 91 ]

Administrating OpenSSO

Updating privileges

The use case requires the packt-services-user-location and packt-servicesuser-blog to be self-modifiable for the users who possess these attributes as part of their profile. As a security precaution only certain attributes are writable by the end user of the OpenSSO server. The administrator can override these, based on the privileges assigned to the administrator. If there is a need to permanently make certain profile attributes writable by the normal user, the administrator must update the default delegation policies. This can be accomplished by editing the appropriate policies. Follow these simple steps in sequence: 1. Export the specific policy named SelfWriteAttributes under / sunamhiddenrealmdelegationservicepermissions: ./ssoadm list-policies -u amadmin -f /tmp/.passwd_of_ amadmin -e /sunamhiddenrealmdelegationservicepermissions -p SelfWriteAttributes -o /tmp/exported_delegation_policy.xml

2. Append the new attributes packt-services-user-location and packtservices-user-blog under UserSelfCheckCondition in the exported file / tmp/exported_delegation_policy.xml. 3. Delete the policy named SelfWriteAttributes under / sunamhiddenrealmdelegationservicepermissions: ./ssoadm delete-policies -u amadmin -f /tmp/.passwd_of_ amadmin -e /sunamhiddenrealmdelegationservicepermissions -p SelfWriteAttributes

4. Add the updated policy from /tmp/exported_delegation_policy.xml: ./ssoadm create-policies -u amadmin -f /tmp/.passwd_ of_amadmin -X /tmp/exported_delegation_policy.xml -e / sunamhiddenrealmdelegationservicepermissions

That is all. Now the user's location and blog entry attributes can be written by the end user from their profile page.

[ 92 ]

Chapter 3

Testing the changes

After completing the customization steps as previously discussed above, if you did not see any errors in the process, then you are successful in completing the customization process. Now restart the OpenSSO server. Once the server is up and running, log in as a top level administrator and try to create a new user identity from the Subjects | User tab. In the New User creation page you should see the Packt Services User Status attribute with a default value Active (set as the default value by the amUser.xml) as shown in the following screenshot. The other two attributes will also show up in the console, but those will not mandate a value to be set at the time of the user creation. It is because they are not required as per the schema definition.

[ 93 ]

Administrating OpenSSO

Let us test as a normal user. Log out from the server and log back in as a normal user, Indira Thangasamy with password secret12. When you inspect the end user profile page, two new attributes Packt Services User Location and Packt Services User Blog Entry are displayed, and it is an editable text box as shown in the following screenshot:

Summary

In this chapter, you were introduced to OpenSSO administration interfaces, a browser-based administrative console, and a command line interface called ssoadm. There are more subcommands that will be introduced as you progress through the book. Administrative console provides more flexibilities to access them than its command line counterpart. Yet, the command line interface provides certain functionalities such as exporting server configuration data that is not available from the console. I'm sure you are pretty excited to know what will be coming in the next chapter. Next, I'm going to dive deep into the nitty-gritty details of the services provided by OpenSSO, including Authentication and Session. Authentication and Session works in tandem to issue a Single Sign-On token to a user request. [ 94 ]

Authentication and Session Service You might have noticed that OpenSSO requires authentication to perform any kind of activity, whether to read the audit records or to access a particular user identity, irrespective of the access point (GUI or CLI). So authentication is a must in order to interact with the server. What is authentication anyway? Well, authentication is the process of identifying and proving the identity of an entity; for example, a user, a computer, or an application. Typically authentication is established by verifying a username and password or a digital certificate in a Public Key Infrastructure (PKI) deployment. Authentication service is a key function of the OpenSSO server; all the unauthenticated requests to the server pass through this service first. It is highly likely that a malicious user could employ a brute force attack on this service to guess a password of another user, and this kind of attack could lead to a DOS (Denial of Service). The server does provide a slew of measures (such as account lockout on invalid credentials) to prevent these kind of attacks. OpenSSO comes with extensive authentication modules that support most of the commercial authentication protocols. If you do not find the one that you are looking for, then it is easy to plugin your authentication module using the Java Authentication and Authorization Service (JAAS) Service Provider Interface (SPI). At the end of the chapter there is an example of how to add a custom authentication module to the server.

Authentication and Session Service

On the other hand the session service, which is also a core part of the server, works in association with the authentication and logging service to complete the authentication process. Once the identity of the user or application is verified, a valid session will be created in the server instance memory (and in the session repository if configured). A session is a time period between the successful authentication (a login event) and revocation of authentication (a logout event). You can learn more about the session life cycle in the later part of this chapter. A successful authentication results in a valid session of course and which is subjected to the session quota limitations. I am planning to leverage the ssoadm command line tool for creating the examples for this chapter. Using the console for this purpose is a trivial task. In this chapter we are going to learn about the following concepts of OpenSSO: • • • • • •

What is authentication service? Various cookies and their roles Types of authentication modes Out of the box support for authentication protocols Adding a custom authentication module Session service and its features

Authentication process

The authentication service of the OpenSSO system can be accessed via a web browser. It also provides an XML and Java interface, which enable non-web based applications to authenticate to OpenSSO. Any Java application uses the Java APIs either locally or remotely. Non-Java applications can use the XML messages sent over HTTP(S) to authenticate to the server. The authentication user web interface is based on the Model-View-Controller (MVC) architecture design framework, in order to facilitate the most dynamic and customizable user interface by clearly separating the presentation layer from business logic. This interface provides dynamic and customizable means for gathering authentication credentials requirements of all plugged in authentication modules at runtime via a single phase or multi-phase user interaction. A single phase authentication, such as a username and password authentication, is in many cases no longer considered as secure in the enterprise world, as users tend to use "easy-to-remember" and hence "easy-to-guess" passwords, such as their family name and/or date of birth. This prompts security product vendors to provide a more secure way of performing authentication using the multi-phase authentication process. In the multi-phase (or multi-factor) authentication, a user is authenticated by means of verifying at least two credentials, one what they know (such as PIN) and what they own (such as Securid Fob). For this reason it is sometimes known as strong authentication. A session or a token or SSO token all refer to a valid authenticated identity's session and these terms are interchangeably used throughout this book. [ 96 ]

Chapter 4

Invariably the authentication framework is responsible for creating the session for the authenticated identity. It does provide an extensive feature set to address various deployment use cases including running behind a firewall, proxy, or a load balancer (LB). There is a special web application called distributed authentication (DA) that grants access to the authentication interface in the demilitarized zones (DMZs). Without these the clients such as the OpenSSO policy agents need to penetrate two levels of firewalls in secure deployments in the DMZs. There is one caveat though. In the federation SSO you are still required to penetrate the DMZ. The authentication process begins when the client identifies the type of authentication and module instance. Then it looks up to the specific module configuration for the callback information. Once all the callback requirements (this callback depends on the module) are completed successfully then the identity principal is determined to set in the session token—this principal is referenced across the OpenSSO. An appropriate exception LoginException is thrown when any of the required callbacks fail or any other error occurs in the authentication process. Final session issuance is subject to the user profile requirement settings of the realm as mentioned in section the User Profile Requirement section.

Cookies in OpenSSO

The Single Sign-On (SSO) session is based on a browser cookie. A cookie is a small collection of information that can be transmitted to a calling browser, which retrieves it on each subsequent call from the browser so that the server can recognize calls from the same client. A cookie is returned with each call to the site that created it, unless it expires. Sessions are maintained automatically by a session cookie that is sent to the client when the session is first created. The session cookie contains the session ID, which identifies the client to the server on each successive interaction. In OpenSSO there are multiple cookies involved, and not all the cookies are set every time. Let us look at these cookies, their values, and the time when they will be set during the authentication process as shown in the following table. It is also possible that custom cookies are set in a cross domain single sign-(CD-SSO) in the scenario with cookie hijack prevention mode enabled, but in a simple deployment configuration only the cookies described in the first table are relevant.

[ 97 ]

Authentication and Session Service

Authentication types and URL parameters

Authentication service provides numerous options to access its services from clients which we will discuss shortly. The browser-based user interface is predominantly used in the OpenSSO deployments, nevertheless, there are applications that require zero page or zero interaction login. In this case there can be no interaction during the authentication as all the credentials and associated data will be presented to the authentication service in one single pass. The server will use the provided information to issue the SSO token, provided the credentials submitted are verifiable. To achieve this in the OpenSSO there are parameters that can be supplied along with the authentication URL. These parameters are frequently used in the deployment to invoke a specific realm configuration or to redirect the browser to a different location such as the protected resource (Chapter 6 deals with the protected resources) after authentication. A parameter is a name/value pair appended to the end of the login URL. The parameter starts with a question mark (?) which is followed by the form name=value. Multiple parameters are appended using an ampersand (&) symbol. Cookie name

Is customizable

Default value

Description

Login Context Cookie

Yes, using the property

AMAuthCookie

It is the authentication cookie set at the beginning of the authentication process, discarded after successful authentication.

com.sun. identity.auth. cookieName

SSO Token Cookie

Yes, using com. iplanet. am.cookie.name

iPlanetDirectoryPro

It is set after successful authentication, it is the actual session cookie forwarded to the client applications.

Load Balancer Cookie

Yes, using the properties

amlbcookie

It is the load balancer cookie that enables to set the server affinity based on this cookie. Use this cookie in your LB to configure the session persistence, though the session persistence is not mandatory to set but it is recommended that customers use session persistence to improve the performance.

01

com.iplanet. am.lbcookie. name com.iplanet. am.lbcookie. value

[ 98 ]

Chapter 4

Cookie name

Is customizable

Default value

Description

Persistent Session

Yes, using the property

DProPCookie

Cookie

com.iplanet. am.pcookie.name

It is set only when the persistent cookie feature is enabled and the URL parameter iPSPCookie=yes is present in the login URL

These parameters play the vital role in determining what kind of authentication is being requested by the client. Broadly there are seven different kinds of authentication types supported by the OpenSSO: • • • • • • •

Module Level Service Role User Realm (domain and organization) Resource

To perform any of these authentication types, the primary requirement is to have each configuration created. Authentication instances are the minimum requirement for this. An authentication instance is a copy of a generic type of a particular authentication protocol service; for instance, the RADIUS authentication service. Each instance of a particular type has identical template structure but unique values for the instance properties. All the authentication protocols are defined as a service with specific XML schema when the server is configured. Custom authentication modules can be created at any point of time.

Module

A module-based authentication can be invoked using the module parameter along with the authentication URL. The value for the module could be any valid authentication instance name that has already been created in the server. A URL of this form http:// opensso.packt-services.net:8080/opensso/UI/Login?module=packt-radius invokes the RADIUS authentication service to authenticate the user. packt-radius is

the instance created from the RADIUS generic service provided by the OpenSSO. On successful authentication the session properties AuthType with value packt-radius (representing the instance name of the module) and IndexType with a value module_ instance (identifying the session is created with module-based authentication) will be set. There are other properties in the session along with these two properties. Please refer to the section titled 'Session Properties found later in this chapter. [ 99 ]

Authentication and Session Service

A module-based authentication can be disabled by the realm administrator by setting the sunEnableModuleBasedAuth=false in the core authentication settings.

Level

While creating the authentication module instances there is a configuration property that takes a numeric value as the authentication level. This can be considered as the authentication strength for each module and can be set to a higher value for strong authentication modules such as RSA SecurID. Classified data can be protected with higher authentication levels. For example, an employee and a financial manager can have access to the corporate documents with a minimum-strength authentication level. When the financial manager wants to access the company's confidential financial data, he will be forced to authenticate to a higher authentication level. In such scenarios, level-based authentication would be appropriate. It uses the parameter authlevel to invoke the level-based authentication using the URL of the form: http://opensso.packt-services.net:8080/opensso/UI/ Login?authelevel=22. When the current session is already on the higher strength then any attempt to authenticate to a lower strength will not be honored using the same session. When there are multiple modules configured with the same strength, then the client will be presented with the list of options to choose from.

Service

A service-based authentication relies on the authentication chain configuration. An authentication chain can be created with one or more authentication module instances. Authenticating using the authentication chain requires all the module instances in the chain to be satisfied unless the OPTIONAL keyword is specified. If any one of them fails, then the whole authentication process will be halted. A service-based authentication can be performed by appending the service parameter along with the login URL and a valid authentication chain name. A URL of http://opensso.packt-services.net:8080/opensso/UI/ Login?service=mychain form will invoke the service-based authentication using the authentication chain named mychain. In this type of authentication, the session property IndexType will be set to service to denote the type of authentication.

[ 100 ]

Chapter 4

User

It is yet another flexibility provided by the authentication service to fine tune the authentication types to the user identity level. A realm administrator can configure specific module instances for each of the users by leveraging the user-based authentication feature of the server. A user-based authentication can be invoked by supplying the user parameter along with a valid OpenSSO user identity's name. Assuming the user jsmith configured to access the LDAP authentication module instance, this user will invoke the http://opensso.packt-services.net:8080/ opensso/UI/Login?user=jsmith to get in to the system. In this type of authentication the session property IndexType will be set to user to denote the type of authentication. This property can be leveraged by the remote applications to determine what kind of authentication mechanism is used by the client to obtain the session.

Role

A role based authentication is pretty much the same as of the user-based authentication except that instead of user parameter, role will be used in the URL. In lieu of a username, a role identity name will be used at the time of invoking the authentication service. This type of authentication is supported only in the legacy mode of the OpenSSO server, that is you should configure the Access Manager Repository to perform a role based authentication. If you have configured a proper authentication chain for the role manager, a role-based authentication for the manager role can be performed using http://opensso.packt-services. net:8080/opensso/UI/Login?role=manager. In this type of authentication the session property IndexType will be set to role to denote the type of authentication.

Realm

If you have noticed in the URLs that we have used so far, it does not mention in which realm the users need to be authenticated. However, the server knows what needs to be done if no realm parameter is present in the URL. It will assume the root realm on seeing no realm in the URL or it will use realm aliases. The realm parameter is used to tell the server the realm that the client is trying to authenticate to. An invocation of http://opensso.packt-services.net:8080/opensso/UI/Login?realm=/ sales&module=sales_ldap will present the LDAP authentication page for the user to authenticate into the sub realm sales, provided a valid sales_ldap instance exists. The domain and org parameters are meant to be used in the legacy Access Manager Repository's co-existence mode in the same manner as the realm parameter.

[ 101 ]

Authentication and Session Service

Resource

All the authentication types that we have discussed in the preceding sections are predetermined, in the sense that the invoking client knows what kind of credentials are required for the page being requested. Every time the same kind of authentication modules will be presented. In certain deployments, customers might want to dynamically (at the runtime) choose a particular authentication type based on the clients' environment properties. For example, a banking institution may enforce a strong authentication when the client is accessing the application from a different geographic location than its usual place. To address the dynamic selection of authentication module resource-based authentication can be leveraged. A resource-based authentication works in concurrence with the OpenSSO policy service. It is a policy services that advises the authentication service what kind of authentication module to invoke after evaluating the clients environment parameters. Resource authentication is based on the client environment variables defined in the HTTP request parameters and/or HTTP request header. After receiving a request for access, the authentication service passes the resource name and appropriate environment parameters to the policy service to determine the authentication type to be used. The policy service returns an advice message to indicate the appropriate authentication type to call. The client is then prompted for the appropriate credentials for the authentication type. The key here is that the policy that protects the resource (typically a URL) should contain the logic to determine what type of authentication is to be used based on the clients' environment parameters such as IP address. [http://developers.sun.com/identity/reference/techart/ ipresenvauthopensso2.html#uc2] A resource-based authentication can be invoked either via supplying resourceURL= or resource=true&goto= parameters. For example, if the resource http://www.google.com is configured with appropriate resource conditions, then any one of the following URLs initiate a resource-based authentication http://opensso.packt-services.net:8080/ opensso/UI/Login?resource=true&goto=http://www.google.com or http://

opensso.packt-services.net:8080/opensso/UI/Login?resourceURL=http:// www.google.com. Without a goto parameter, resource=true alone will not initiate the resource based authentication.

[ 102 ]

Chapter 4

Other authentication URL parameters

There are other authentication parameters that can be used to configure certain use cases that could not be covered by the parameters discussed so far. For instance the zero-page login does return a valid session provided the submitted credentials are correct. Not all the authentication protocols can be used with zero-page login. For example, the challenge/response authentication modules may not participate in the zero page authentication. Any username and password-based authentication such as LDAP can be used for zero-page authentication. The username and password information is sent to the server using the URL parameter IDTokenN where N is a numeric value. When you type http://opensso.packt-services.net:8080/ opensso/UI/Login?IDToken1=demo&IDToken2=changeit in the browser location bar you would be presented with the profile of the demo user. Note that there is no login page rendered for the zero-page login. By the way, all the URL parameters are case sensitive.

IDToken parameter

The IDToken parameter is used to map the credentials from the authentication page from the field values that user's enter through the browser. This parameter enables a user or application (an agent identity) to pass authentication credentials using the login URL, allowing authentication without accessing the authentication service user interface. As described above, the zero-page login leverages this parameter to obtain a session. This is very useful to quickly validate whether the agent identity can authenticate to the server using http://opensso.packt-services.net:8080/ opensso/UI/Login?module=Application&IDToken1=myagent&IDToken2=myage nt. Note that the IDToken0 is used for the username as opposed to IDToken1. This is applicable only for the agent identity authentication (module=Application). For

security reasons you should always consider using the HTTP/POST for submitting user credentials over the wire. OpenSSO 8.0 Update 2 release made some security fixes that disabled the GET method for submitting the credentials.

goto and gotoOnFail parameters

In an enterprise deployment, OpenSSO can be used as a trusted authentication authority to issue the Single Sign-On tokens. Users can use this token to access the other applications such as calendar, e-mail, and so on from a corporate portal. On successful authentication users needs to be sent back to a secure portal, and this can be accomplished by using the goto parameter along with the authentication URL. The OpenSSO policy agents extensively use goto to redirect the client back to the protected resource after authentication.

[ 103 ]

Authentication and Session Service

In this example the user, after authenticating to the realm / sales, will be taken to Google's home page. http://opensso. packt-services.net:8080/opensso/UI/Login?realm=/ sales&goto=http://www.google.com.

Akin to the successful login, it is also possible to use goto after a successful logout from the system. Some financial institutions recommend closing the browser after logout and this can be achieved by using the goto parameter to send the user's browser to the post logout page where the message about closing the browser can be displayed. Unlike the goto parameter, the gotoOnFail parameter can be used to send the client to a page after an authentication attempt has failed. For instance clients can be redirected to a password reset page or a self-registration page in case of authentication failure. In this case the users will be redirected to the password reset page of the OpenSSO server after the authentication failure. http:// opensso.packt-services.net:8080/opensso/UI/ Login?realm=/sales&gotoOnFail=http://opensso1.packtservices.net:8080/opensso/password?realm=/sales.

In general these authentication success and failure URLs can be configured at different levels for a user identity. The order of precedence would be the goto to the URL, user, role, realm, and Global. First it will look for the success (or failure) URL in the url goto (gotoOnFailure) parameter, if not available it will check in the authenticated identity's profile for the attribute iplanet-am-auth-login-successurl (iplanet-am-auth-login-failure-url), which if not available will be checked in the service role and so on, and so forth.

locale parameter

OpenSSO has the capability of displaying screens that are translated into languages other than English. These localized screens can be configured for the authentication process as well as for the console itself. The locale=language-locale parameter allows the specified locale to take precedence over any other defined locales for the authentication process.

[ 104 ]

Download from Wow! eBook

Chapter 4

If you want to invoke the authentication interface in French locale use: http://opensso.packt-services.net:8080/opensso/ UI/Login?locale=fr.

The login locale will be determined in this order: •

locale parameter in the URL

•

Locale defined in the user's profile using the attribute preferredlocale

•

Locale set by the browser

•

Locale defined in the core authentication properties

•

Locale defined in the OpenSSO platform service

•

JDK locale

•

Operating system locale

The locale derived from this logic is stored in the user's session and the server uses it for loading the localized authentication module only. After successful authentication, the locale defined in the preferredlocale attribute of the user's profile is used.

arg parameter

Clients can use this parameter to force the browser to kill any existing sessions for the server and create a new session based on the credentials submitted. This will be useful if you are already logged into a realm but wanting to authenticate to a different realm. Without the arg parameter you will be prompted with a page for confirmation to kill the existing session. Zero page authentication of this type would destroy any existing sessions and obtain a new session for the user demo. http:// opensso.packt-service.net:8080/opensso/UI/Login?arg=n ewsession&IDToken1=demo&IDToken2=changeit.

[ 105 ]

Authentication and Session Service

iPSPCookie parameter

This parameter is used to instruct the server to create a persistent cookie, provided the persistent cookie is enabled (Persistent Cookie Mode) in the core authentication properties. If the persistence cookie is not enabled at the server side, then sending this parameter does not make any difference. A persistent cookie is one that continues to exist even after the browser window is closed. If the user is successfully authenticated and the browser is closed, the user can login with a new browser session and will be directed to the console without having to authenticate again. By default this cookie is valid for 25 days, but it can be configured for a lesser value too. This stays valid until it expires or the user explicitly logs out from the server by clicking on the logout link. Just closing the browser does not remove this persistent cookie. To view the cookie you have to look into your browser cookie database with name, DProPCookie. Note that it is different from the session (SSO token) cookie, iPlanetDirectoryPro. A persistent cookie will create a session cookie every time the browser is reopened with the login URL with iPSPCookie=yes as a parameter. A persistent cookie can be created by invoking the authentication URL with the iPSPCookie parameter with a value true. Here is how you can obtain a persistent session for the user demo. http://opensso.packt-service.net:8080/opensso/ UI/Login?iPSPCookie=yes&IDToken1=demo&IDToken2=c hangeit.

ForceAuth parameter

The ForceAuth=true query parameter forces the user to authenticate even if the user currently has a valid session. This parameter is useful in the following case. When the user is performing the session upgrade with this parameter then the existing session ID and the session property values such as the max user session are retained with the existing session's value. Only the moduleAuthTime and AuthType properties are updated. This is useful if the admin wants to control the max session time of a user by allowing to upgrade the session without extending the current session. Without the ForceAuth=true parameter, whenever a user does a session upgrade after a successful upgrade, the user's max session time (for that matter all the session-related properties) will be reset to the original value configured in the session service of the realm to which the user authenticated.

[ 106 ]

Chapter 4

PersistAMCookie parameter

In an authenticated session, the cookie is lost if the browser is restarted. There have been OpenSSO deployment requests to make it persistent so that the cookie would be saved on disk and survive browser restart. This is different from the persistent cookie DProPCookie. With persistent cookie a new session is created because of DProPCookie, not the original one that we lost due to browser restart. The PeristentAMCookie parameter is about retrieving the same session instead of creating a new one. It is just a handle to the current and active session. The expiry time for this persistent cookie would be much shorter and should be set less than idle session time that is configured for the current session. The PersistAMCookie parameter will save the OpenSSO Enterprise session cookie to the memory disk, thereby allowing an application (other than the browser) on the same machine to read it and create an SSO token. You need to set a valid numeric value (N) in minutes for the com.iplanet.am.cookie.timeToLive property in the OpenSSO server to enable the cookie to be stored in the disk for N minutes.

Authentication modules, instances, and chains

Without a doubt, authentication is a vast area and it is hard to cover all the different ways to perform the authentication, nevertheless, let us see how to create, update, and delete authentication instances of frequently used modules. In this context an authentication module refers to the global service schema, an instance on the hand is an instance of a module. A chain is a collection of one or more authentication instances. So to create a chain we should have an instance created already. So, you really want to understand how to create and manage the authentication instances. Let us use ssoadm for all of the examples in this section assuming you have already set up the ssoadm tool. We would be using the sub commands shown in the table extensively while implementing the examples throughout this chapter. Sub command add-auth-cfg-entr

Purpose

create-auth-cfg

Creates an authentication chain on a given realm

create-auth-instance

Creates authentication instances with system default values

delete-auth-cfgs

Deletes authentication configurations

delete-auth-instances

Deletes authentication instances

Adds authentication configuration entry

[ 107 ]

Authentication and Session Service

Sub command get-auth-cfg-entr

Purpose

get-auth-instance

It returns the properties of a configured authentication instance

list-auth-cfgs

List of authentication configurations

list-auth-instances

To list the configured authentication instances on a given realm

register-auth-module

Registers authentication module

show-auth-modules

Shows the supported authentication modules in the system

unregister-auth-module

Unregisters authentication module

update-auth-cfg-entr

Gets authentication configuration entries

update-auth-instance

To update pre-existing authentication module instance properties

Gets authentication configuration entries

LDAP authentication

One of the very common types of authentication protocol is LDAP. OpenSSO is capable of authenticating pretty much any of the LDAPv3 compliant servers including the Sun Directory Server Enterprise Edition, but is not limited to Microsoft Active Directory, IBM Tivoli Directory server, OpenDS, and so on. I will explain the whole authentication instances and chains life cycle and how to create, update, use, and delete them using the LDAP module as an example. The rest of the modules can be manipulated in the same manner as the one described here. That is the reason the sections are titled generically and not qualified with LDAP.

Creating an authentication instance

To create the LDAP authentication module only a few properties are required, the LDAP server name, port, bind distinguished name, and its password. In this scenario OpenDS is used as the authentication server. To create an LDAP authentication instance named packt-ldap with all system default values, you can use the following command: ./ssoadm create-auth-instance -m packt-ldap -t LDAP -u amadmin -f /tmp/. opensso.pass -e /sales

This sub command can be used to create any type of authentication module instance. The key here is the -t option to ssoadm that determines what type (showauth-modules sub command returns all the supported authentication modules in OpenSSO) of authentication module instance to be created. [ 108 ]

Chapter 4

Updating an authentication instance

When the authentication instance is created for the first time it will be created with the system default values. Apparently it needs to be updated to work with customer-specific servers. It can be updated by invoking the update-auth-instance sub command. There is more than one way (-a and -D) to update the properties of an instance, and it depends on the nature of the update whether one or the other option can be used. If the instance requires one or two property changes, then use option -a else use option -D. In this scenario, to update the instance packt-ldap with your LDAP server details, invoke: ./ssoadm update-auth-instance -e /sales -m packt-ldap -u amadmin -f /tmp/.opensso.pass -a "iplanet-am-auth-ldap-server=ldapserver. packt-services.net:5389" "iplanet-am-auth-ldap-binddn=cn=openssouser,ou=opensso adminusers,dc=opensso,dc=java,dc=net" "iplanet-am-auth-ldap-bind-passwd=amsecret12"

It changes only the values of iplanet-am-auth-ldap-bind-dn,iplanet-am-authldap-bind-passwd and iplanet-am-auth-ldap-server. The rest of the properties are set to its original values.

Reading an authentication instance

It is always good practice to make sure that the configuration has been updated with the correct values. It can be done using the get-auth-instance sub command. Note that password values will not be displayed: ./ssoadm get-auth-instance -u amadmin -f /tmp/.opensso.pass -e /sales -m packt-ldap Authentication Instance profile: iplanet-am-auth-ldap-ssl-enabled=false iplanet-am-auth-ldap-return-user-dn=true iplanet-am-auth-ldap-search-scope=SUBTREE iplanet-am-auth-ldap-base-dn=dc=opensso,dc=java,dc=net iplanet-am-auth-ldap-search-filter= iplanet-am-ldap-user-creation-attr-list= iplanet-am-auth-ldap-server=ldapserver.packt-services.net:5389 iplanet-am-auth-ldap-user-search-attributes=uid iplanet-am-auth-ldap-invalid-chars=*|(|)|&|! iplanet-am-auth-ldap-user-naming-attribute=uid iplanet-am-auth-ldap-bind-dn=cn=openssouser,ou=opensso adminusers,dc=open sso,dc=java,dc=net iplanet-am-auth-ldap-auth-level=0 [ 109 ]

Authentication and Session Service iplanet-am-auth-ldap-server2= iplanet-am-auth-ldap-bind-passwd=******** iplanet-am-auth-ldap-server-check=15

At any time if you want to update some of the properties of a particular authentication instance, all you need to do is to perform the following sequence of steps: •

Obtain the properties using get-auth-instance into some file and allow it to call props.txt

•

Update the required values in the file props.txt

•

Update the instance using update-auth-instance sub command by providing -D props.txt

Using an authentication instance

Now that we have created an LDAP authentication instance packt-ldap in the / sales sub realm, one can authenticate using the packt-ldap instance by invoking

http://opensso.packt-services.net:8080/opensso/UI/Login?module=packtldap&realm=/sales, provided that module-based authentication is not disabled in the /sales sub realm.

Deleting an authentication instance

From time to time, business requirements change. Consequently administrators have to remove certain realms and associated authentication configurations. OpenSSO offers interfaces to remove the instances using UI console or just calling appropriate ssoadm sub commands. The following command line shows how an authentication instance can be removed from the system: ./ssoadm delete-auth-instances -u amadmin -f /tmp/.opensso.pass -e /sales -m packt-ldap

This will remove the authentication instance packt-ldap from the realm /sales instantly, provided this instance is not referenced by any of the authentication chains in the realm.

[ 110 ]

Chapter 4

Authentication chains

A Single Sign-On token is issued to a prospective client as soon as the credentials are verified. Well, this process is absolutely right with respect to a module-based authentication. Let us look at a use case where customers want to enforce more than one module type (for example, SecurID and LDAP) authentication before issuing a valid SSO token. How do we address this case? Authentication chains are the way to go for these kinds of use cases. An authentication chain is basically a collection of one or more authentication module instances whose order of invocation and control flow is arbitrated by the JAAS flags (refer to http://download.java.net/jdk7/docs/ api/javax/security/auth/login/Configuration.html for more details on these JAAS flags). Overall authentication succeeds only if all Required and Requisite modules succeed. If a Sufficient module is configured and succeeds, then only Required and Requisite modules prior to the Sufficient module need to have succeeded for overall authentication to succeed. If no Required or Requisite modules are configured for an application, then at least one Sufficient or Optional module must succeed. Authentication chaining is achieved using the Java Authentication and Authorization Service (JAAS) framework integrated into the Authentication Service. The difference between a module and chain-based authentication is, in the latter case, all the module instances have to be authenticated (in compliance with JAAS flags) successfully to receive an SSO token. Even if one of the module instances in the chain fails then the whole authentication process will be considered a failure. Once authentication to all module instances in the chain has been successfully achieved, further verifications are performed by the authentication framework to make sure all the user identifiers authenticated in the chain are in some form referred to a unique identity principal. For this purpose it may consult the identity's alias list stored in the profile data store. Once this validation is successful, an SSO token is issued to the user. Unlike the authentication chain the module-based authentication is required to satisfy only one specific module instance. The authentication chains provide the infrastructure to implement user, service, and, role-based authentication in the OpenSSO server.

[ 111 ]

Authentication and Session Service

Creating an authentication chain

An authentication chain can be created using already existing module instances. So the prerequisite is to have the required module instances created. The example that is about to be explored creates an authentication chain named packt-chain with a NT and Unix authentication module instances that requires to obtain an SSO token. The first two ssoadm calls create the module instances NT and Unix respectively so it can be used to create the chain, packt-chain: ./ssoadm create-auth-instance -u amadmin -f /tmp/.opensso.pass -t NT -m packt-nt -e /sales /ssoadm create-auth-instance -u amadmin -f /tmp/.opensso.pass -t Unix packt-unix -e /sales

-m

Again we are dealing with the sub realm /sales, if you have noticed you will see that all the sub realms are referenced with absolute names with prefix root (/). It is legitimate to use the relative names such as sales in the command line; nevertheless, we will continue to use absolute names while referencing the sub realms for clarity. All right, the module instances are ready; let us create the authentication chain using the following command: ./ssoadm create-auth-cfg -u amadmin -f /tmp/.opensso.pass -m packt-chain -e /sales

The authentication chain packt-chain will be created with default settings, which means none of the authentication module instances are assigned yet to this chain. Associating the module instances to the chain can be done using the update-authcfg-entr sub command as shown in the following section.

Updating an authentication chain

It is not uncommon to add or remove module instances to and from a chain. While adding the module instance to the chain, the administrator must tell whether it is REQUIRED, OPTIONAL, SUFFICIENT, or REQUISITE. Let me invoke the ssoadm with an appropriate sub command to perform this. This step can be accomplished from the UI console as well, but it is a trivial procedure so let us not spend time on that: ./ssoadm update-auth-cfg-entr -u amadmin -f /tmp/.opensso.pass -m packtchain -e /sales -a "packt-nt|REQUIRED" "packt-unix|REQUIRED"

This will complete the update process for the chain packt-chain with NT and Unix modules as required. When this chain is assigned to a user, that user has to successfully authenticate to the NT domain and Unix system to get an SSO token. The shared state options can be set by appending with the JAAS flag after a vertical bar.

[ 112 ]

Chapter 4

Reading an authentication chain

Let us verify whether the authentication chain is indeed created with what we intended: ./ssoadm get-auth-cfg-entr -u amadmin -f /tmp/.opensso.pass -e /sales -m packt-chain Authentication Configuration's entries: [name=packt-nt] [flag=REQUIRED] [options=] [name=packt-unix] [flag=REQUIRED] [options=]

If you notice any discrepancy in the values you have set, it can be corrected using the UI console or by invoking ssoadm with the update-auth-cfg-entr sub command.

Using an authentication chain

An authentication chain can be called by the clients in many ways, by performing a service, role, or user-based authentication. To perform a service-based authentication using chains there is no special setup required. An authentication service URL should be accessed with a parameter service=chainName. In this example it translates into this URL: http://opensso.packt-services.net:8080/ opensso/UI/Login?realm=/sales&service=packt-chain. On calling the above URL the server will render the NT authentication first, followed by the Unix authentication page irrespective of the NT authentication status. It happens because of the REQUIRED flag. To learn more about these flags and how they impact the authentication control flow refer to http://download.java.net/jdk7/docs/api/ javax/security/auth/login/Configuration.html. For now, assume that the NT and Unix modules are properly configured to authenticate to a valid server. A more detailed procedure on configuring these modules is discussed in the later parts of this chapter.

Performing a user-based authentication

To perform a user-based authentication using the packt-chain, a valid user must be created and have packt-chain assigned to that user as described below: ./ssoadm create-identity -u amadmin -f /tmp/.opensso.pass -i packt-user -t User -a "cn=Packt User" "sn=UserP" "userpassword=packsecret" -e /sales ./ssoadm set-identity-attrs -i packt-user -t User -u amadmin -f /tmp/. opensso.pass -a "iplanet-am-user-auth-config=packt-chain" -e /sales

[ 113 ]

Authentication and Session Service

A user identity packt-user has been created by the create-identity sub command. Followed by that, the packt-chain is assigned to the user to enable user-based authentication. With that it completes the configuration required to initiate a user-based authentication using this URL: http://opensso.packtservices.net:8080/opensso/UI/Login?user=packt-user&realm=/sales. It is evident that user-based authentication is triggered via the URL parameter, user. Once user-based authentication is invoked it calls up the profile attribute to identify which authentication chain had to be called. In this case it is packt-chain, it pops up with an NT module followed by Unix. In both cases the user has to authenticate with the same principal of packt-user or if another user identifier is used (as NT and Unix domain user) then it should be an alias for the packt-user. It is the key requirement to get a valid SSO token. In the same manner, an authentication chain can be assigned to a role identity to perform role-based authentication.

Deleting an authentication chain

It is the final phase of the authentication chain's life cycle. A chain can be removed by simply removing the name from the realm under the authentication tab. To remove the chain from CLI use the ssoadm sub command delete-auth-cfgs as shown in the following command line: ./ssoadm delete-auth-cfgs -u amadmin -f /tmp/.opensso.pass -m packt-chain -e /sales

It is worth noting that removing an authentication chain will not remove any of the module instances that were part of the chain, and so will be the authentication chains assigned to the users. You need to explicitly remove them to clean up the references to the deleted authentication chain.

Authentication modules

It is out of the scope of this book to cover various authentication modules supported by the OpenSSO server. In spite of that, some of the non-trivial authentication protocols will be discussed in this section from a configuration perspective to make it work with the OpenSSO server. No authentication protocol specifications will be dealt with here, except where it is relevant.

[ 114 ]

Chapter 4

LDAP

Light Weight Authentication Access Protocol (LDAP) is one of the popular authentication protocols, widely used in the enterprises. There are many commercial LDAP servers including the Sun Directory Server Enterprise Edition and Microsoft Active Directory available in the market. Technically OpenSSO can authenticate to any LDAPv3 compliant directories with simple bind. To configure this module you need to have a valid LDAP server name, port, bind DN (with read and search privileges), and a password. You may notice some differences in the way certain LDAP controls are handled in the OpenSSO. It requests LDAP_CONTROL_PWEXPIRED and LDAP_CONTROL_PWEXPIRING to reset users' password when it is about to expire or has already expired.

Active Directory

It is unknown to me why this authentication module was introduced when the LDAP module can already handle the authentication to the Active Directory (AD) server. My guess would be the need to support the complex password policies. AD password policies are extensive as opposed to LDAPv3, so it makes sense to have a dedicated module to support them. That said, OpenSSO does not yet support the Active Directory domain policies, there is a request for enhancement open for this issue. The minimum required values to configure an AD module are AD server name, service port, a valid DN, and password. An Active Directory authentication module can be created using the following command line: ./ssoadm create-auth-instance -u amadmin -f /tmp/.opensso.pass -t AD -m packt-ad -e /sales

Data store

A data store authentication module is the simplest authentication module that does not require any extra configurations to be set up. It uses the configured data store in the realm to find the users to authenticate to, so it is called a DataStore authentication module. To successfully authenticate as a DataStore module, a valid data store should have been configured in the realm that invokes the DataStore module. It consists of only one property which is the authentication level. For some reason, if you do not want the data store to be used for authentication using the DataStore module, then simply uncheck the User in the Data Store profile page labeled Identity Types That Can Be Authenticated attribute. A data store authentication module can be created using ssoadm in the following manner: ./ssoadm create-auth-instance -u amadmin -f /tmp/.opensso.pass -t DataStore -m packt-datastore -e /sales

[ 115 ]

Authentication and Session Service

Anonymous

With the advent of social networking portals, content aggregation and customizations are becoming a necessity to attract the users to the sites. Before even making the user sign up for a particular site or service the promoters have to convince the users with the features they offer to impress them. Typically all the portals and the social websites by default provide a decently customized (for example http://my.yahoo.com) page. This provides a precursor on how a user can customize their page. These default customizations could be associated with an anonymous session because at this point the user is not yet signed up for the service. Anonymous authentication can be leveraged to support those kinds of use cases to provide guest level access to certain pages or content. All the default customizations can be associated to the default anonymous user who would have the least privileges and session time compared to the other registered users. In the OpenSSO server, the anonymous user can be added depending on the deployment requirements even though there is a default user called anonymous created in the root realm. When a client accesses the server with the Anonymous module there is no need to provide user identity and password: ./ssoadm create-auth-instance -u amadmin -f /tmp/.opensso.pass -t Anonymous -m packt-anonymous -e /sales

The command that we just saw creates an Anonymous authentication module instance in the sales realm. An anonymous authentication can be invoked by calling the authentication service with a module instance named packtanonymous, such as http://opensso.packt-services.net:8080/opensso/UI/ Login?realm=sales&module=packt-anonymous.

Certificate (X.509)

In the enterprises with PKI (Public Key Infrastructure) centric security environment, it may be possible that clients will be allowed to authenticate using only X.509 client certificates. In general, HTTP over SSL/TLS can happen with and without client certificates being required. It is configurable in the web container settings of the container where the authentication service is running. Applications that require certificate authentication can be configured to use the OpenSSO certificate authentication module that relies on the container to request the client certificate. When the clients access the applications that are protected by X509 certificates, the underlying webcontainer forces the client to submit their user certificate in order to serve the request. This certificate will be extracted by the OpenSSO certificate authentication module. In a simple certificate authentication, OpenSSO relies on the container's SSL protocol handshake mechanism. As soon as the handshake is successful, the authentication service issues an SSO token. [ 116 ]

Chapter 4

In theory this is very acceptable, yet there are other provisions to ascertain the veracity of the client certificate by matching the certificate sent by the client with the one stored in the matched user's profile. The other possibilities include validating with the certificate revocation lists (CRL) and OCSP (Online Certificate Status Protocol) by making the relevant configuration settings in the certificate authentication module instance at the OpenSSO server side. Enabling the OCSP makes sure that every time the user authenticates, their certificate is validated for its status using the OCSP URL that is part of the user certificate.

Configuring Tomcat in SSL using CA signed certificate

Let us learn together how quickly one can enable the SSL for the second Tomcat container you have configured in Chapter 2. The first step in setting up the SSL is to create a JKS-based key store using the keytool command: keytool -genkey -alias packt-cert -keystore packt-keystore. jks -keyalg RSA -dname "cn=opensso2.packt-services. net,ou=identity,o=packt services,l=livermore,c=US" -storepass mysecret -keypass mysecret

This step completes the key store creation with the name packt-keystore.jks with both key and store password set to mysecret. The cn value in the -dname option must match your OpenSSO web container's name to successfully perform the SSL server authentication. To show the OCSP validation, I am generating a certificate request that will be signed by a certificate authority (CA). For creating self-signed certificates there are plenty of resources available on the Internet including http:// tomcat.apache.org/tomcat-5.5-doc/ssl-howto.html: keytool -certreq -keystore packt-keystore.jks -keyalg RSA -alias packt-cert -file certreq.txt -storepass mysecret -keypass mysecret

The certificate signing request is available in the file certreq.txt and it can be sent to a CA (in this case the Sun Certificate Management Server) which will issue a valid SSL server certificate. The server certificate obtained from the CA should be imported into the key store using the key tool command.

[ 117 ]

Authentication and Session Service

Assuming the signed server certificate is stored in the cert.txt file and the root CA certificate is in the file cacert.txt, the following sequence of commands import these certificates in the packt-keystore.jks: keytool -import -alias "mahogany Root CA" -keystore packtkeystore.jks -file cacert.txt -storepass mysecret -keypass mysecret keytool -import -alias packt-cert -keystore packt-keystore.jks -trustcacerts -file cert.txt -storepass mysecret -keypass mysecret

That concludes the configuration of the JKS-based key store to setup the SSL for the Tomcat container instance running on port 9090. Copy the packt-keystore.jks to the $CATALINA_HOME/conf directory (following the convention from Chapter 2, it would be /export/ssouser/tomcat-9090/apache-tomcat-6.0.20/conf/). The second instance is running on HTTP port 9090. There is no SSL port configured yet. A secure HTTP listener must be created using the key store we have just created. To create the secure listener add the following fragment of the code in the server.xml of your Tomcat instance:

You should now be able to access the Tomcat container https://opensso2.packtservices.net:9191. The rest of the OpenSSO configuration on secured the HTTP

port is the same as of the non-secure port configuration except you invoke the secure port using the https prefix in the URL. In the configuration clientAuth=want tells the Tomcat container that the client certificate is optional but not required. It helps other users who do not have client certificates continue to receive the service.

[ 118 ]

Download from Wow! eBook

Chapter 4

We are dealing with the server opensso2 (https://opensso2.packt-services. net:9191/opensso) only for this module because it requires SSL with client authentication enabled to perform the certificate-based authentication. We will resort to http://opensso.packt-services.net:8080/opensso for the rest of the modules for simplicity, even though all the modules shall work with secure HTTP protocol as well. Presumably you have configured the server using the https mode (this is the prerequisite) and set up the CLI tool for this instance. To perform the certificate-based authentication, create a realm sales (to be consistent with the other examples) and authentication instance packt-cert to invoke the certificate authentication: ./ssoadm create-realm -e sales -u amadmin -f /tmp/.opensso.pass ./ssoadm create-auth-instance -m packt-cert -t Cert -u amadmin -f /tmp/. opensso.pass -e /sales

Once the web container secures the HTTP port, the client authentication is enabled. Whenever the secure port is accessed a client certificate issued by the same certificate authority will be requested by the web container, with that the service running at the port 9191 cannot be accessed. The certificate authentication module in the OpenSSO server simply relies on the client authentication validation by the underlying container in the default configuration we have just created, with the name, packtcert. As soon as the certificate authentication is invoked using the URL https:// opensso2.packt-services.net:9191/opensso/UI/Login?module=packtcert&realm=sales you will notice a message User has no profile in this

organization. It means the authentication was successful but OpenSSO cannot locate a valid profile for the user to issue an SSO token. There are configuration settings that can be tuned to get the desired behavior either by dynamically creating a profile for the user in the subject CN or by disabling the requirement to have a profile for the authenticated user. If you want to enable the OCSP validation, just set the corresponding property to true, something like the following command line: ./ssoadm update-auth-instance -m packt-cert -u amadmin -f /tmp/.opensso. pass -e /sales -a "iplanet-am-auth-cert-check-ocsp=true"

You need to make sure the OpenSSO server and OCSP server are time synchronized to properly enforce the certificate status.

[ 119 ]

Authentication and Session Service

HTTP basic authentication

It is designed to support the HTTP basic authentication (RFC2617) which is not considered to be a secure method of user authentication (unless used in conjunction with some external secure system such as SSL/TLS), as the username and password are passed over the network as cleartext, and so use of this module in the OpenSSO deployment is strongly discouraged. It relies on the LDAP and DataStore authentication modules in the backend to provide the username and password attributes. In order to provide HTTP basic authentication, you need to assign the DataStore or LDAP module to the realm where HTTP basic authentication is being configured.

Membership

Membership module is otherwise known as the self-registration authentication module. It is self-explanatory. This module is used to provide an interface to the users to sign up to a new website or service without any administrator's intervention. It comes with a default disclaimer page that can be customized by the customer to fit to their needs. The automatic username generation feature helps a lot to avoid duplicate username registrations.

JDBC

The Java Database Connectivity (JDBC) authentication module provides a mechanism to allow OpenSSO to authenticate users using any SQL database that provides JDBC technology-enabled drivers. The connection to the SQL database can be either directly through a JDBC driver or through a JNDI connection pool. Out of the box OpenSSO provides a default implementation (com.sun.identity. authentication.modules.jdbc.ClearTextTransform) that requires a password field to be in plain text in the database table. Of course customers can implement their own password syntax transform plugin processing class. A sample JDBC authentication module instance is created using the ssoadm tool which is given for your reference below: ./ssoadm create-auth-instance -m packt-jdbc -t JDBC -u amadmin -f /tmp/. opensso.pass -e /sales ./ssoadm update-auth-instance -m packt-jdbc -u amadmin -f /tmp/.opensso. pass -e /sales -D /tmp/mysql.txt

[ 120 ]

Chapter 4

All the relevant properties are stored in the file, /tmp/mysql.txt. The contents of this file are listed below: sunAMAuthJDBCAuthLevel=0 sunAMAuthJDBCPasswordSyntaxTransformPlugin=com.sun.identity. authentication.modules.jdbc.ClearTextTransform sunAMAuthJDBCJndiName=java:comp/env/jdbc/samplePool sunAMAuthJDBCStatement=select PASSWORD from JDBC_AUTH_USER_DATA where USER_NAME = ? sunAMAuthJDBCUrl=jdbc:mysql://mysql.packt-services.net:3306/jdbc_auth_ testdb?autoReconnect=true sunAMAuthJDBCDbuser=dbuser sunAMAuthJDBCDbpassword=dbsecret12 sunAMAuthJDBCDriver=com.mysql.jdbc.Driver sunAMAuthJDBCConnectionType=JDBC sunAMAuthJDBCPasswordColumn=PASSWORD

One the key requirements for this module is to copy the JDBC drivers to the OpenSSO web application's WAR file. For example, if users are authenticating to a MySQL database, then the mysql-connector-java-5.1.10-bin.jar file should be available under the WEB-INF/lib directory of the opensso.war file. Having this available ensures that the authentication framework can locate the proper JDBC driver to connect to the backend database to complete the authentication. Both MySQL 4.x/5.x and Oracle 10g/11g (for Oracle appropriate driver should be copied to the WEB-INF/ lib location) are known to support this authentication module.

HOTP

Strong authentication is gaining more importance in the industry as well as among the customers. OpenSSO already provides interfaces to integrate the strong authentication modules that use hardware tokens such as Secure Computing SafeWord. Existing strong authentication modules address the requirements; however, it imposes the users to carry the hardware token wherever they go. Instead if we could use the devices that consumers always have handy, such as a cell phone to authenticate it would greatly improve the usability. One Time Password (OTP) in OpenSSO is one such attempt to send the one time password to consumers' cell phones, so the requirement of a hardware token can be eliminated. You can find more details on this module implementation in the product documentation.

[ 121 ]

Authentication and Session Service

SecurID

It is a very straightforward process to integrate the existing authentication infrastructure servers with very little effort with OpenSSO service deployment. RSA SecurID® is a two-factor authentication based on something you know (a password or PIN) and something you have (an authenticator)—providing a much more reliable level of user authentication than reusable passwords. The RSA server could be running anywhere. To configure OpenSSO to work with RSA Securid, first create an RSA host agent profile(sdconf.rec) from RSA ACE server administrative console for the host where OpenSSO server is configured. Then copy this sdconf.rec (cit) to the OpenSSO host. This file should be included in the configuration of the SecurID module instance. In the Sun Java System Access Manager, SecurID was implemented as a separate daemon process which needs to be running prior to invoking the SecurID authentication. In the OpenSSO server the whole SecurID authentication is platform agnostic pure Java implementation. If Java 2 security is enabled in the container, then you need to add proper Java EE policies for the RSA SecurID module. It is available only on Express and Enterprise builds of OpenSSO.

SafeWord

Secure Computing (now McAfee) provides for the enterprise a token-based twofactor authentication scheme (based on the generation of one-time-passwords) for access to their internal networks or applications from the Internet. OpenSSO offers an authentication module to authenticate the users to an existing SafeWord server in the enterprise. Administrators can create an instance of the SafeWord module by providing the existing SafeWord server name, port, and protocol version (101,200, and 201). It is available only on Express and Enterprise builds of OpenSSO.

RADIUS

The RADIUS (Remote Authentication Dial-In User Service) is yet another authentication protocol widely used in the industry. OpenSSO has been tested with the freeradius (http://freeradius.org/) server extensively. Integrating the RADIUS authentication into OpenSSO is a trivial process.

[ 122 ]

Chapter 4

Unix

The Unix authentication module is a Pluggable Authentication Module (PAM) that authenticates user identifiers known to the Solaris or Linux system on which OpenSSO is installed. This module makes use of an authentication helper daemon called amunixd which opens a socket on a specified port in order to listen for Unix authentication requests. This daemon process is separate from the authentication process. The authentication depends on the PAM service account name (usually located in /etc/pam.d directory) that needs to be included in the Unix authentication module instance. Typically, this account name defaults to other (the other is a PAM authentication profile that is available in the out-of-the-box Solaris OS)for Solaris, and password for Linux systems, and some Linux use passwd in the PAM account name. Remember to run the amunixd as root user as running any other user will not let you authenticate to the Unix systems. The amunixd binary can be found in the opensso.zip under the tools/helpers directory. This authentication module is not available on the Windows systems for obvious reasons.

Windows NT

Like the Unix authentication module, NT module is used to authenticate to the Microsoft Windows Active Directory Domain. It uses samba client (smbclient) to authenticate to the Microsoft Windows domain using the password and username supplied in the authentication user interface. The OpenSSO server administrator should place the samba client binary under the //bin directory. Here is a sample command to create the NT authentication module instance: ./ssoadm create-auth-instance -m packt-nt -t NT -u amadmin -f /tmp/. opensso.pass -e /sales ./ssoadm update-auth-instance -m packt-nt -u amadmin -f /tmp/.opensso. pass -e /sales -a "iplanet-am-auth-nt-domain=AMQA" "iplanet-am-auth-nthost=anna"

To perform NT module-based authentication use the URL of the form

http://opensso.packt-services.net:8080/opensso/UI/Login?module=packtnt&realm=sales.

The host name for the NT domain should not be a fully qualified name. Look for more troubleshooting information in the last chapter.

[ 123 ]

Authentication and Session Service

Windows Desktop SSO

The Windows Desktop SSO authentication module is a Kerberos-based authentication plugin module used for the user who has a Kerberos account in Unix KDC or Windows 2000™ / Windows 2003™ domain controller. It allows the already authenticated user in a Kerberos Distribution Center (KDC) to automatically log in to OpenSSO without re-submitting the credentials thereby achieving the Single Sign-On. The user presents the Kerberos token to OpenSSO through the SPNEGO (Simple and Protected GSS-API Negotiation Mechanism) protocol in order to perform Kerberos-based Single Sign-On to OpenSSO through this authentication module. The user application-like browser on the client side must support the SPNEGO protocol to authenticate itself. Since the user does not need to send any credentials in plain text for authentication, Windows Desktop SSO is one of most secure authentication modules that transparently achieves SSO in a Windows Desktop Environment.

Core

The core authentication module is meant to store the system (global) and realmspecific generic authentication configuration information such as account lockout. At the global level, custom authentication Pluggable Authentication Module Classes will be added to the core authentication service properties. When a new realm is created this service is automatically assigned system default values. It can be configured to match the deployment-specific requirements. A new instance of this module cannot be created; hence, it may not be used as part of the authentication service URL like module=core_instance. There are interesting configurable properties in this service. Let us look at a few of them.

User profile requirement

The authentication framework completes the process by issuing an SSO token for the identities that successfully authenticate. One of the key requirements besides satisfying the actual credential validation is whether the authenticated identity possesses a profile in the configured data stores. In the default settings if an identity is authenticated successfully, but the framework failed to locate the profile (basically the attributes of the user, such as mail, telephonenumber, and so on) then an SSO token will not be issued. In some deployment scenarios it may be required to issue a token without a profile or by just dynamically creating a profile at runtime (it is a one time creation). This kind of behavior can be altered by setting appropriate values for the schema attribute iplanet-am-auth-dynamic-profile-creation that can have four possible values false, true, ignore, and createAlias.

[ 124 ]

Chapter 4

User profile (iplanet-am-auth-dynamic-profile-creation) determines the profile status of a successfully authenticated user. The following are the user profile types: Dynamic: Dynamic specifies that on successful authentication the authentication service will create a user profile, if one does not already exist in one of the configured data stores. The SSO token will then be issued. The user profile is created in the realm's configured user data store: ./ssoadm set-realm-svc-attrs -u amadmin -f /tmp/.opensso.pass -e / sales -s iPlanetAMAuthService -a "iplanet-am-auth-dynamic-profilecreation=true"

Dynamic With User Alias: Dynamic With User Alias specifies that on successful authentication, the authentication service will create a user profile that contains the user alias list (iplanet-am-user-alias-list) attribute which defines one or more aliases for mapping a user's multiple profiles: ./ssoadm set-realm-svc-attrs -u amadmin -f /tmp/.opensso.pass -e / sales -s iPlanetAMAuthService -a "iplanet-am-auth-dynamic-profilecreation=createAlias"

Ignore specifies that a user profile is not required for the authentication service to issue an SSO token after a successful authentication. It means the authentication framework will not even look for the profile in the configured data stores: ./ssoadm set-realm-svc-attrs -u amadmin -f /tmp/.opensso.pass -e / sales -s iPlanetAMAuthService -a "iplanet-am-auth-dynamic-profilecreation=ignore"

Required specifies that on successful authentication the user must have a user profile in the realm's configured user data store in order for the authentication service to issue an SSO token: ./ssoadm set-realm-svc-attrs -u amadmin -f /tmp/.opensso.pass -e / sales -s iPlanetAMAuthService -a "iplanet-am-auth-dynamic-profilecreation=false"

[ 125 ]

Authentication and Session Service

Setting user profile attributes in an SSO token

Typically, there are clients from remote locations who get authenticated by the OpenSSO server. The remote application might want to render a customized page based on certain attributes of the authenticated identity. For example, it wants to display weather based on the postal zip code. Well, this can be done after obtaining the SSO token and a subsequent query can be made to the OpenSSO server to retrieve the attributes. Apparently it involves some extra time and effort by the client application. Instead, if the server could send the properties required by the clients as part of the SSO session token, it can be retrieved by the client by making a simple get property call on the SSO token. This would be the ideal case where the client virtually does not do any extra work nor does the server. Let us take an example where we want the OpenSSO server to set the CN and mail attributes of the user in the SSO token so that the remote clients (such as the policy agents) can retrieve and use them. To configure using CLI for the sub realm /sales, invoke the following command line: ./ssoadm set-realm-svc-attrs -u amadmin -f /tmp/.opensso.pass -e /sales -s iPlanetAMAuthService -a "sunAMUserAttributesSessionMapping=mail|SSO. token.mail" "sunAMUserAttributesSessionMapping=cn|SSO.token.commonname"

Note in the above example, the cn is the userProfileAttribute and SSO.token. commonname is the nameInSSOToken. In this example the users' mail attribute and cn attributes are configured to be available in the SSO token after a successful

authentication (irrespective of the authentication type). Of course, this scenario makes sense only when the user profile is set to REQUIRED in the core authentication service. A caveat on setting session attributes in this way is that any changes on these profile attribute values will not be updated in the session object unless a session upgrade happens.

The client can issue getProperty on the SSO token object (getProperty(sessionObject,"am.protected.SSO.token.mail")) to obtain the value of the user's mail attribute. These properties are protected in the sense the values of these properties cannot be changed at the remote client side, but can only be updated at the server side. Here is the content of a typical session object obtained after authenticating as user indira with the URL http://opensso.packtservices.net:8080/opensso/UI/Login?module=DataStore&realm=sales: [ 126 ]

Chapter 4

Ignoring the rest of the properties for now (a later section deals with it), let us focus on the highlighted ones. If you recall we wanted to call the mail as SSO.token.mail in the session property but actually there is no SSO.token.mail but am.protected. SSO.token.mail. It is because the string am.protected is prefixed by the server to make sure these properties are not modifiable by anyone but the server itself.

[ 127 ]

Authentication and Session Service

Adding custom authentication modules

I am confident that by now you have a decent idea about the authentication framework and the modules in OpenSSO. There are many built-in authentication modules that could facilitate the integration of OpenSSO with existing authentication infrastructure in the customer's place. It is not uncommon in the customers' deployments, where a lot of legacy type Java or C/C++ thick client applications that heavily relies on the non-browser interfaces. Integrating those applications with OpenSSO could be challenging, and existing authentication modules may not be sufficient to address the use case. Writing custom authentication modules might be inevitable using the application programming interface (API) and service provider interface (SPI) provided by the OpenSSO authentication service. There is a great example provided in the OpenSSO out of the box. It can be accessed via the following URL: http://opensso.packtservices.net:8080/opensso/ samples/authentication/AuthSampleLoginModule.html. It provides a great deal of information on how to implement a custom authentication module. Adding a custom authentication module involves a few simple steps: •

Creating an Authentication Module Callback Requirement file determines the flow of the authentication by including the number of callbacks and time-out values. For this specific example, the module definition file is located under the config/auth/default/LoginModuleSample.xml directory from the root of the OpenSSO web application structure.

•

The next step in the custom authentication module implementation is to create a means to determine the principal of the authenticated entity. The file SamplePrincipal.java implements that logic available in the source/com/ sun/identity/samples/authentication/spi/providers directory.

•

Like any other service in the OpenSSO, the custom authentication module can be added as a service so that module instances can be created. In this example there is no service schema required to keep things simple.

•

Typically the authentication modules can be localized to specific locales by moving the label strings to a property file that can be translated into different languages. In this sample, English is assumed to be the default locale.

[ 128 ]

Chapter 4

•

The process of extending custom authentication modules extend the com.sun.identity.authentication.spi.AMLoginModule class and must implement the init(), process(), and getPrincipal() methods. The Java file LoginModuleSample.java located in ./source/com/ sun/identity/samples/authentication/spi/providers directory implements those methods. Besides these, other possible methods that can be implemented include setAuthLevel(), setLoginFailureURL(), and setLoginSuccessURL() that define URLs to which the user is sent, based on a failed or successful authentication, respectively.

•

The final step would be compiling those Java classes and putting them in the OpenSSO web application. This includes creating the new service, registering the new authentication class, and restarting the server.

In the example, compiling and putting into the web application's WAR are all already performed. Just add the com.sun.identity.samples.authentication.spi. providers.LoginModuleSample class to the core authentication service at the global level as described in the instruction. This sample uses anonymous authentication.

Session Service

The Session Service in OpenSSO is one of the core components that serves as a backbone for the rest of the components to work together for delivering the supported features. It tracks a user's interaction with web applications through the use of session data structures, session tokens, cookies, and other objects. This section attempts to explain some of these concepts and other components of a user's session and properties. Some of the key functions of the Session Service are: •

Create unique session identifiers and maintain session states

•

Manage the session life cycle (create, delete, timeout)

•

Manage session persistence and high availability

•

Secure the session properties

•

Enforce session constraints

The term SSO has multiple meanings and is often misinterpreted. Here is a generic definition, "After a one time authentication, identities can access any application for which they are authorized without having to re-authenticate". This means once the user is authenticated there is no need to re-authenticate again and again to browse protected applications. Specifically with relevance to OpenSSO, the Single Sign On could be interpreted as: after authenticating to OpenSSO, users can access the applications without having to re-authenticate, provided the OpenSSO policy allows the access to the resource being accessed by the authenticated user. [ 129 ]

Authentication and Session Service

There are two kinds of Single Sign-On tokens that are created by the Session Service after a successful authentication. A user SSO token and an application SSO token. The former is the predominantly visible and used by the end users of the protected applications, the latter is often created by the OpenSSO clients such as the policy agents. The user SSO tokens are the real sessions maintained in the Session Service that can be persisted and terminated by the administrator. The following table summarizes the salient features of these tokens. SSO token

App SSO token

Attached to iPanetDirectoryPro cookie

No cookie involved

Session constraints and timeouts enforced by the OpenSSO server

Typically it is a non-expiring token until the agents container is restarted (it can be forced to expire by setting the com.iplanet. am.session.agentSessionIdleTime property in the server side)

Can be terminated by an administrator using the OpenSSO console or ssoadm CLI

Cannot be destroyed explicitly by the OpenSSO administrator

Session high availability feature can be enabled to persist sessions

No session persistence capability

Session Service schema

All the OpenSSO services are defined using a well-defined XML service schema in compliance with sms.dtd. Session Service schema is defined in the / config/xml/amSession.xml file. It is added to the configuration store during the configuration phase of the server. Any customization in the Session Service should happen on this file. As you can see, it is a dynamic service and can support service attributes at the user and role levels provided the underlying user identity store is Access Manager Repository, which is often referred to as legacy mode.

Updating Session Service

It is quite possible that you may want to update the session service properties to customize the session's lifetime. This can be accomplished by an administrator either using the OpenSSO console or command line interface such as ssoadm. The following is a quick way of updating the key session time limits using the ssoadm command line tool: ./ssoadm set-realm-svc-attrs -u amadmin -f /tmp/.opensso_pass -e / -s iPlanetAMSessionService -a "iplanet-am-session-max-session-time=340"

[ 130 ]

Chapter 4

This command configures the user's sessions maximum time to 340 minutes at the root realm.

Session life cycle

The Session Service is responsible for implementing the mechanisms to manage the session state changes which can be triggered by either the user's explicit actions such as invoking a log in or log out or the system events such as cleanup for expired sessions. These session state changes usually depend on the time-dependent behaviors, which may include creation, activation, timing out, and destruction of user sessions.

Session structuring

A session or an SSO token is uniquely identified by the session identifier. The session ID is basically an opaque handle used to locate the session object. The format has the following structure: @# is simply an encrypted ID string. is base64-encoded sequence of pairs. The existing extension

field tags currently include the primary server instance ID, the Site ID, and the session storage. is appended for reference only and is not used by the Session Service. Here is a snapshot of a sample SSO token obtained from the OpenSSO server. AQIC5wM2LY4Sfcx5F4RvwHxOQZ3U/NOCliujsjg6Q1bIy1c=@AAJTSQACMDE=#

In this case AAJTSQACMDE= is the session extension field and the AQIC5wM2LY4Sfcx5F4RvwHxOQZ3U/NOCliujsjg6Q1bIy1c= part is the session opaque, there is no available in this session ID. Session Service provides remote interfaces that can be used by the client to create, update, and destroy sessions.

[ 131 ]

Authentication and Session Service

Session state transition

During the lifetime of the session, it undergoes various state changes before being removed from the session table. The transitions of these session states are controlled by the Session Service based on the user actions or the time-dependent behaviors which are enforced by the Session Service. When a request to create a new user session is triggered, the Session Service generates a new session ID and a new instance of session object. The session object is initially created in the INVALID state with default values of attributes and an empty property list. Newly created sessions do not carry any identity. Once the session is authenticated, session state is updated with all the identity attributes and properties. In case the authentication failed, then the generated session ID is discarded in a session request. In the session upgrade scenario the old session is retained. However, this implementation could lead to a security vulnerability where, in a shared desktop, an attacker pre-generates an INVALID session and then tricks a valid user to authenticate. As a result, both the attacker and the valid user have a valid session. OpenSSO 8.0 Enterprise Update 2 and OpenSSO Express Build 9 addressed this vulnerability by issuing a new session after successful authentication. The transitions in session state triggered by distinct user or system events are depicted in the following figure:

[ 132 ]

Download from Wow! eBook

Chapter 4

Session properties

When a session is created by the Session Service subsequent to a successful authentication of an identity, it by default adds certain core properties that describe the nature of the authentication type, session creation time, and other pertinent information that is critical to track the sessions and to retire them when appropriate. A session's validity is determined by the property set in the server side that is modifiable only by privileged users such as the administrator. There are properties in the session that are not modifiable by any remote client but the server-side modules. The other custom properties that can be set as part of the session are modifiable remotely by any application which possesses the session ID. These custom properties can be used by the remote clients to retrieve some user identity information as part of their session token such as the role of the user. Based on this information the client application could render different user interfaces, based on their role type. Nevertheless, there is another option that customers can use to restrict the remote clients from modifying certain custom session properties. However, this is not an out of the box configuration, one needs to set the com.iplanet.am.session. protectedPropertiesList in the server-side's advanced properties section. For example, if you are setting a session custom property my.security.role=orgAdmin in the users' SSO token that you do not want the remote clients to update, then just set com.iplanet.am.session.protectedPropertiesList=my.security.role in the OpenSSO server side. This can be easily achieved by simply invoking the ssoadm command line tool: ./ssoadm update-server-cfg --servername http://opensso.packt-services. net:8080/opensso -u amadmin -f /tmp/.passwd_of_amadmin -a com.iplanet. am.session.protectedPropertiesList=my.security.role

Here are the some of the system protected properties; these properties cannot be modified by anyone but the OpenSSO server itself. So administrators need not worry about these values being modified by some remote clients: • • • • • • •

AuthLevel AuthType Principal UserId UserToken Organization cookieSupport

[ 133 ]

Authentication and Session Service

• • • • • • • •

authInstant Principals loginURL FullLoginURL Role Service SessionTimedOut AM_CTX_ID

These values can be retrieved from the users' session by various means, for example, the OpenSSO policy agents can be configured to set the users' session attribute values as part of the HTTP header, or a remote client application could use the remote session API to retrieve the values.

Session change notification and polling

In an SSO environment all the protected resources are authorized to be accessible only for the users with a valid SSO token. Well, what happens if the SSO token issued by the OpenSSO server has subsequently been revoked by the administrator? Will the user continue to get access to the protected resource? How does the remote application know that the token has been revoked? This is where session polling and notification come into play. The Session Service framework provides the notification service which allows for session event notifications to be sent to session clients participating in the same SSO environment. The server is capable of sending session event change notifications (push model) to clients who have registered for notifications. Alternatively the clients can periodically poll the server to ask (pull model) for changes in the sessions. These session events may include the session state changes, for example, session creation, session timeout, and session termination events. Either way, the remote application can find out that the user session state has been changed and make appropriate decisions with respect to the resource access. Interestingly, there is a more fine-grained way of receiving change notification for a specific session property that is set as part of the session token. It could be a performance issue if property change notification is set for every property, so use this feature with caution. The administrator can configure a certain property for which the clients wish to receive change notification. It is a two-fold process: first the administrator has to enable the global session property, change notification flag, followed by adding the respective properties in the list of properties for which change notifications will be sent. Here are those two commands using the ssoadm command line tool.

[ 134 ]

Chapter 4 ./ssoadm set-attr-defs -s iPlanetAMSessionService -t Global -u amadmin -f /tmp/.passwd_of_amadmin -a iplanet-am-session-property-changenotification=ON ./ssoadm set-attr-defs -s iPlanetAMSessionService -t Global -u amadmin -f /tmp/.passwd_of_amadmin -a iplanet-am-session-notification-propertylist=my.security.role

The server needs to be restarted for these changes to take effect. Once it is in effect, any change in the property my.security.role will be notified right away to the remote application that has registered for session notification.

Session persistence and constraints

Though it is out of the scope of this book, let us quickly catch up on the session high availability achieved by means of session persistence. For the deployments that require highly available OpenSSO Session Service, one should consider session failover capability provided by the server. It is relatively easy to implement with the least number of supported components, as it does not require any relation database server. It relies on the Berkeley DB component together with Java Message Queue cluster to persist the sessions. For more detailed information, refer to the documentation provided by docs.oracle.com. The enforcement of session quota constraints in the Session Service allows an administrator to limit a user to a specific number of active concurrent sessions based on either the constraint settings at the global level or the configuration associated with the user. With session quota constraints enabled, when there is an attempt to create a new user session, the server enforces the session quota constraints, so that if the session quota for that particular login user has been exhausted, certain actions will be taken based on the desired behavior as configured by the administrator. These actions include denying the login request (DENY_ACCESS), accommodating the new session creation request by destroying the oldest existing session (DESTROY_OLD_SESSION) or by applying customized implementation. Session quota constraints can be enforced in a single OpenSSO server deployment or in a multiple servers clustering environment with session failover enabled. Administrative users are optionally exempted from the session quota constraints as this is determined by the top level administrator role membership.

[ 135 ]

Authentication and Session Service

Summary

In this chapter we learnt at length about various authentication mechanisms supported by the OpenSSO server. With many examples, I have enabled the reader to go through tutorial-like, do-it-yourself kind of steps to perform certain authentication service configuration tasks. Configuring the SSL key stores and enabling secure transport for the Tomcat server would definitely be handy for you to set up the certificate-based authentication. Although most of the authentication services are available out of the box in the OpenSSO, if you need any custom authentication module, it can be easily implemented by following the procedure that is described in this chapter. In the last part of the chapter we did learn a lot about the Session Service and SSO token structure and properties. Session high availability and constraints are one of the critical features to implement production level SSO deployments. In the next chapter, password reset application is introduced along with the user account management. Typically, for security reasons, the enterprises enable certain password policies such as passwords expiring after every three months. In case the password has expired, the authentication page can redirect the user to a self-service password reset application. This will reduce the administrative cost to reset forgotten passwords.

[ 136 ]

Password Reset and Account Management The OpenSSO server offers user identity management through its administrative console and the command line tool, ssoadm. It is pretty important to realize how the authentication determines whether the supplied identity is valid and active. In general, the authentication systems, such as RSA SecurID or Oracle DB that has its own mechanisms to ascertain the active state of the users. If that is so, why does OpenSSO have to check and validate the users? There is a reason for doing so. OpenSSO provides an out-of-the-box account lockout facility to prevent unauthorized access to the system by means of guessing the password. Typically, one can write a simple script to post to the authentication service by generating different passwords, which is essential to password guessing (called "brute force attack"). These kinds of attacks would often constitute a Denial of Service (DOS), as the authentication service will be bombarded with invalid authentication attempts by the rogue script. To prevent this, OpenSSO employs an account lockout facility, wherein the administrator will be able to configure how many invalid password attempts can be made before getting locked out. This is applied on top of the underlying authentication system's imposed account lockout policies. What if my password has expired? How can I enable it? There are two ways to reset the password—request the administrator to enable your account or use the password reset service to reset your expired password. One exception here is that any permanent lockout must be reset by the administrators. It cannot be set to active by using the password reset service. In this chapter, let us look at the following topics: •

Account lockout

•

Password reset application

Password Reset and Account Management

Account lockout

In the OpenSSO, there are four attributes that are validated before issuing an SSO token to a user identity, they are: • • • •

inetuserstatus iplanet-am-user-login-status iplanet-am-user-account-life nsaccountlock

The last attribute is inherited from the Oracle Directory Server Enterprise Edition's base schema. The rest of the attributes are defined in the OpenSSO user schema. Each time an authentication request comes, these attributes are validated before letting the user get an SSO token. The inetuserstatus attribute is the primary attribute that determines whether the user is in an active state. This attribute can take Boolean values to determine active/ inactive state. If this attribute does not exist, then that user is considered as active. Likewise the attribute iplanet-am-user-login-status takes active and inactive Boolean values. This attribute is defined by the Access Manager Repository legacy schema. The attribute iplanet-am-user-account-life does take a date and time value, which describes the expiry date of the account. For example 11/11/2011 12:00 would mean that the account will not be valid after this given date and time. Finally the nsaccountlock takes true or false. A false value denotes the account is not locked. This is an operational attribute set by the Sun Directory Server Enterprise Edition, also referred to as the Oracle Directory Server Enterprise Edition. All these account expiries and account lockouts must be configured for each realm in order to be effective.

Configuring account lockout

In the default OpenSSO configuration, the user account lockout feature is disabled by default. This feature can be enabled using the administrative console or the ssoadm command line tool. From the console, navigate to Access Control | (Top Level Realm) | Authentication | All Core Settings. Then enable account lockout by checking the box as shown in the following screenshot:

[ 138 ]

Chapter 5

When enabled, e-mail notifications are sent to administrators regarding any account lockouts as well as those recorded by the Logging Service. In order to get the e-mail notification, the administrator must configure the SMTP server name and port properly in the server configuration; otherwise the e-mail notification feature will not work (Please refer to the next section for more details on SMTP configuration.) Here is a simple way to set these properties using the ssoadm tool: ./ssoadm update-server-cfg -s http://opensso.packt-services.net:9090/ opensso -u amadmin -f /tmp/pass -a com.iplanet.am.smtphost=smtphost. packt-services.net com.iplanet.am.smtpport=25

Only authentication modules that throw an invalid password exception can leverage the account locking feature. These include Active Directory, Data Store, HTTP Basic, JDBC, LDAP, RADIUS, SafeWord, SecurID, and Unix. OpenSSO supports two types of account lockout: •

Physical lockout

•

In-memory lockout

[ 139 ]

Password Reset and Account Management

Both of these have their own merits. It is up to the deployment requirements, based on which, one or the other mode could be employed. Let us briefly look at the features of each mode.

Physical lockout

This is the default lockout behavior, initiated by changing the status of a specified LDAP attribute in the user's profile to inactive. The specified LDAP attribute (in this example it is inetuserstatus) is defined as the value of the Lockout Attribute Name attribute in the Core authentication module as shown in the preceding screenshot. When physical account lockout is enabled, an attribute in the user data store (in this case sunAMAuthInvalidAttemptsData) is used to hold information regarding the authentication attempts. This information includes: •

Invalid attempts count

•

Last failed time

•

Lockout time

•

Lockout duration

Here is the typical XML message that gets stored in the attribute sunAMAuthInvalidAttemptsData: 2128242171745000

Physical lockout can be enforced in the multi-server environment or in a site with more than one OpenSSO server, serving for high availability, because the invalid attempts data are persisted as part of the user profile attribute. However, in-memory lockout is server-specific. Even though they belong to a site, each server could potentially hold different invalid attempt counts for a given user.

[ 140 ]

Chapter 5

In-memory lockout

In-memory lockout is enabled by changing the value of the Login Failure Lockout Duration attribute (which defines how long a user must wait after a lockout, before attempting to authenticate again) to a value greater than 0. This is in addition to enabling the Login Failure Lockout Mode check box. The user's account is then locked in memory (stored in the container's memory) for the number of minutes specified. The account is unlocked after the time period has passed. There are special considerations when using the memory locking feature: •

If the OpenSSO server is restarted, all accounts locked in memory are unlocked because the stored data is lost due to server restart

•

If a user's account is locked in memory and the administrator resets the account lockout mechanism to physical lockout (by changing the value of the Login Failure Lockout Duration to 0), then the user's account will be unlocked in memory and the lock count reset

•

If the Failure URL attribute in the user's profile is defined, neither the lockout warning message nor the message indicating that the account has been locked will be displayed; the user will be redirected to the defined failure URL as expected

Once the lockout mode is enabled based on this configuration, the OpenSSO server authentication service will throw warning messages before locking out due to an invalid password attempt. Here is a typical message that will be shown to the user who entered an invalid password for a valid account.

[ 141 ]

Password Reset and Account Management

Customers will be able to employ any one of these solutions based on their nature of usage. In a deployment where high availability is a requirement, it would be wise to deploy the physical lockout because it is enforced in multiple server environments.

Applying a password reset

Self-service password reset is defined as any process or technology that allows users who have either forgotten their password or triggered an intruder lockout, to authenticate with an alternate factor, and repair their own problem, without calling the help desk. It is a common feature in identity management software. Typically users who have forgotten their password launch a self-service application from an extension to their workstation login prompt, using their own or another user's web browser, or through a telephone call. Users establish their identity, without using their forgotten or disabled password, by answering a series of personal questions, using a hardware authentication token, and responding to a password notification e-mail. Users can then either specify a new, unlocked password, or ask that a randomly generated one be provided. OpenSSO currently provides the option of sending a random password after answering the personal questions correctly. OpenSSO provides a feature-rich web application that can be customized to let the end users reset their forgotten password. An administrator can automatically redirect their login failed users to this page in order to enable the users to reset their password without the administrator's intervention.

Prerequisites

The OpenSSO password reset application will be deployed as part of the services deployment. Unlike the Access Manager the password reset application is embedded as part of the OpenSSO web application itself, no special deployment task is required to get the application. Before starting off with the password reset application configuration, the following prerequisites must be met: • • • •

OpenSSO deployed and configured with Access Manager Repository plugin or a Supported Data Store Valid e-mail address for the users who want their password to be reset through this service Valid SMTP service host and port configured in the OpenSSO Server User Data store must be Sun Directory Server Enterprise Edition or OpenDS

[ 142 ]

Chapter 5

You need to also pay attention to update the amPasswordResetModuleMsgs_ en.properties (or the appropriate locale) file to provide a valid name for the property lockOutE-mailFrom, as the default value will cause sendmail problems. The OpenSSO password reset service can be configured to work in association with the backend data stores' password policy controls, and so it will be honored by OpenSSO. As I have described earlier, the password reset application can be configured with the Sun Directory Server or OpenDS besides the Access Manager Repository plugin. In this section I am going to use OpenDS-based configuration, so that others can easily replicate the procedure in their environment as OpenDS is freely available. You can find more details on these user data stores in Chapter 8.

Configuring the password reset service in OpenSSO

Password reset is one of the services that can be assigned for each realm. In order to start the process, first select the password reset service for the realm and provide necessary details for the service attribute as shown in the following screenshot. It is implicit that the OpenSSO server will be configured with a data store that is pointing to the OpenDS server. Refer to Chapter 8 for learning about supported identity stores.

Assigning service and update service attributes

To assign the password reset service, log in as top level administrative user, and assign the service as shown in the following screenshot:

Once the service is selected, you will be asked a series of questions pertaining to the password reset service in the next screen, including the account lockout feature that will be applied when the end user enters an incorrect answer. This is analogous to the invalid password attempt discussed in the previous section of this chapter. [ 143 ]

Password Reset and Account Management

The service attribute values are self-explanatory. However, there is one particular attribute that decides whether OpenSSO would honor the password policy of the backend data store. The attribute Force Change Password on Next Login determines whether to look for the password control from the backend data store. In the same manner, checking on Personal Question attribute enables the end user to provide their own question besides selecting administrator-provided choices. The end configuration of the password reset service will look as shown in the following screenshot:

[ 144 ]

Chapter 5

With that, we complete the configuration of the OpenSSO password reset service. Now let us create a user identity jdoe and prepare that identity to be used with the password reset application to change the password of the user jdoe. To create the user, you can use either of the interfaces provide by the OpenSSO. The profile will appear like the following screenshot, from the console:

Please note that the user profile consists of a valid e-mail address. This is the key for the password reset application to reset and send the new password to the end user. This e-mail should be accessible by the end user with a username and password that is not the same as the one being reset. According to the configuration, the end user should be able to add their own question to their password reset profile. Let us add a custom question for the user jdoe as shown in the following screenshot:

[ 145 ]

Password Reset and Account Management

This screen can be arrived at by logging into the end user's account and by clicking on profile | Password Reset Options link:

These configurations are sufficient for the end user to reset his/her forgotten password using the OpenSSO password reset application. In this example, by accessing the URL http://opensso.packt-services.net:9090/opensso/ password/.

[ 146 ]

Chapter 5

Upon invoking the preceding URL you will be asked a series of questions as configured in the system and as the one configured in your profile. The following sequence of screenshots shows the actions that occur when the user initiates the password reset process.

As you will notice, the two questions are shown to the user—one that the OpenSSO administrator configured and the other added by the end user, jdoe. The administrator can add as many as five questions to the system. The end user is only allowed to add one question in the default configuration. The password of the user will be reset once the questions are answered correctly. If not, they will be asked again until they are answered correctly or locked out if lockout is enabled. You will be given warning about the lockout as shown in the following screenshot:

[ 147 ]

Password Reset and Account Management

If the password is reset, then two e-mails will be sent to the e-mail address in the user's profile—one e-mail will inform the user that there was an attempt to reset his account, and the other mail will contain the actual system generated password. If an e-mail does not exist in the user's profile or a problem arises with the SMTP server or the e-mail address is invalid, appropriate information will be printed on the browser screen. A typical message will be, "Your password has been reset but we are unable to send it to you. Contact your administrator". In this case, you should contact the administrator. A success message will appear somewhat as given in the following screenshot:

After this process, you can log in to your e-mail account to get the temporary systemgenerated password. You must change the password after logging into the OpenSSO. Often, users fail to change the password that was generated by the system. This could be a potential security vulnerability as the password has been e-mailed. It could be read by any malicious user. To circumvent these kinds of issues, the backend directory servers enforce a mechanism to change the password at the first login attempt. The OpenSSO password reset feature can honor this if the backend directory has been setup with a password policy to force the users to change the password during the first login attampt. Now let us see how one can configure the OpenDS server to enforce the password change after an Administrator Reset.

[ 148 ]

Chapter 5

Creating and assigning OpenDS password policy

The OpenSSO password reset application works with and even without enabling the OpenDS password policy. If the OpenSSO server is configured such that it does not force the user to change his password through the password reset application, then there is no need to create this policy in the OpenDS server. However, the said configuration is highly discouraged from a deployment perspective, so exercise caution while unchecking this box in the password reset service configuration.

Creating OpenDS policy

To create the OpenDS password to force the password change after an admin reset, one can use the dsconfig utility. There is lot of documentation available on the Internet on how to create the password policies. Here is the simple command line to create the policy: dsconfig create-password-policy \
  -set default-password-storage-scheme: Salted\ SHA-1 \
  --set password-expiration-warning-interval: 86400 \
 --set password-attribute: userpassword \ 


--set force-change-on-reset: true \
  
--set max-password-age: 172800 \




--type generic \
  --policy-name OpenSSO\ Users\ Policy \
 --hostname

opends.packt-services.net \


--trustAll \
 --port 5519 \
 --bindDN cn=Directory\ Manager \
 --bindPassword ****** \
 --no-prompt

--set force-change-on-reset: true is the key part of this policy. This tells the OpenDS that users who belong to this policy will have to reset their password after an administrator changes their password.

Once you create the preceding policy, it appears in the config.ldif of OpenDS in the following form: # OpenSSO Users Policy, Password Policies, config dn: cn=OpenSSO Users Policy,cn=Password Policies,cn=config
 objectClass: ds-cfg-password-policy
 objectClass: top


[ 149 ]

Password Reset and Account Management ds-cfg-default-password-storage-scheme: cn=Salted SHA-1,cn=Password Storage Sc
hemes,cn=config 
ds-cfg-password-expiration-warning-interval: 86400 s
 ds-cfg-password-attribute: userpassword
 cn: OpenSSO Users Policy
 ds-cfg-force-change-on-reset: true
 ds-cfg-max-password-age: 172800 s

Assigning the policy to a user

After the policy has been created in the backend data store, in this case OpenDS, we need to assign this policy to a user or group so it will take effect for those assigned entries. These policies can be assigned to groups or individual entries. Here, for simplicity let us assign the policy to our jdoe user. This assignment can be done using the ldapmodify tool as mentioned here: ldapmodify -h opends.packt-services.net -p 5389 -D"cn=directory manager" -w dssecret12 -c -f /tmp/mod

where the file /tmp/mod contains: dn: uid=jdoe,ou=people,dc=opensso,dc=java,dc=net changetype:modify add: ds-pwp-password-policy-dn ds-pwp-password-policy-dn: cn=OpenSSO Users Policy,cn=Password Policies,cn=config

This will complete assignment of the policy to the end user identity.

Forcing password change after reset

Now let us revisit the password reset initiate process by invoking the password reset application URL http://opensso.packt-services.net:9090/opensso/password. Go ahead; answer the questions correctly for the user jdoe as you did in the earlier section. Once you successfully reset the password, go to your e-mail and get the temporary system generated password, and try to log in to the server. At this point you will notice two kinds of behaviors—either your authentication with the new password will repeatedly fail or you will see a new screen, as follows:

[ 150 ]

Download from Wow! eBook

Chapter 5

If you see the password reset screen as shown in the preceding screenshot, then that is the correct behavior. It means OpenSSO honors the force password change control coming from the OpenDS. It is important that you enable the Force Change Password on next login in the password reset service configuration otherwise OpenSSO will not know about the password reset control coming from OpenDS. Well, what if you keep on failing the authentication with the new system generated password? It is very likely that your default authentication service for the realm has been set to something other than the LDAP module. You must use the LDAP authentication module in order see this force password change screen. This LDAP instance must point to the OpenDS server where the user profile is located.

Behind the scenes

Once you reset the password of the user, you will see that the pwdreset attribute will set to true in the profile of that user identity. This is the key information for the OpenSSO LDAP authentication module to render the force password change page for the end user. Before the password is changed by the end user the pwdreset attribute will be preset in the profile with a value true: ldapsearch -h opends.packt-services.net -p 5389 -D"cn=directory manager" -w dssecret12 -b"dc=opensso,dc=java,dc=net" "uid=jdoe" pwdreset dn: uid=jdoe,ou=people,dc=opensso,dc=java,dc=net pwdreset: true

[ 151 ]

Password Reset and Account Management

After performing the force password change through the OpenSSO LDAP authentication module, the pwdreset attribute will be removed from the profile of the end user: ldapsearch -h opends.packt-services.net -p 5389 -D"cn=directory manager" -w dssecret12 -b"dc=opensso,dc=java,dc=net" "uid=jdoe" pwdreset dn: uid=jdoe,ou=people,dc=opensso,dc=java,dc=net

Location of secret questions

The questions and the answers configured by the administrator and the users are stored as part of the user profile data. These are stored in an encrypted form in order to maintain privacy and secrecy. The attributes that store these questions and answers are part of the OpenSSO identity schema. There is no option to store them in existing user attributes. Here is the how user entry jdoe appears in the backend data store: dn: uid=jdoe,ou=people,dc=opensso,dc=java,dc=net postalAddress: 6151 Al way inetUserStatus: Active uid: jdoe userPassword: {SSHA}GxEwEI8lnuVfcNqW8CDu/g1vxVEPyyPl1GqHNg== sunAMAuthInvalidAttemptsData:: PEludmFsaWRQYXNzd29yZD48SW52YWxpZENvdW 50PjA8L0 ludmFsaWRDb3VudD48TGFzdEludmFsaWRBdD4wPC9MYXN0SW52YWxpZEF0PjxMb2NrZWR vdXRBdD 4wPC9Mb2NrZWRvdXRBdD48QWN0dWFsTG9ja291dER1cmF0aW9uPjA8L0FjdHVhbExvY2 tvdXREdX JhdGlvbj48L0ludmFsaWRQYXNzd29yZD4= objectClass: iplanet-am-auth-configuration-service objectClass: sunIdentityServerLibertyPPService objectClass: sunAMAuthAccountLockout objectClass: sunFederationManagerDataStore objectClass: iplanet-am-managed-person objectClass: iPlanetPreferences objectClass: sunFMSAML2NameIdentifier objectClass: person objectClass: inetorgperson objectClass: organizationalperson objectClass: inetuser objectClass: iplanet-am-user-service objectClass: top givenName: John iplanet-am-user-password-reset-question-answer: AQICedz7aDUl9rJQbVekeLksWS2zr+

[ 152 ]

Chapter 5 x80x30S63PCVSLKGBr3rVNbJDYiiFEle7YnzEm iplanet-am-user-password-reset-question-answer: AQICedz7aDUl9rJ0C5mnO1eJvv1Rj8 jqqY5KpkV6Ts5T3wGDXcDb3WGz4fRedJ7gxLvJcFNdPkUENpFv/zvqTUwgUg== cn: John Doe telephoneNumber: 408-276-0000 sn: Doe iplanet-am-user-password-reset-force-reset: true mail: [email protected]

Summary

Unlike other access management products, OpenSSO provides a decent level of identity provisioning and management features. User identity status is properly maintained to keep their status up-to-date, by leveraging special attributes of its own as well as honoring the status attributes by the underlying data stores. To circumvent the denial of service type attacks, OpenSSO employs various lockout mechanisms—a permanent and temporary lockout which customers could deploy in their specific environments. Another salient feature that is embedded as part the OpenSSO server application is the password reset application. Customers can reduce their operational cost by enabling their users to reset their forgotten password by redirecting them to the OpenSSO password reset application. This application could potentially improve the user experience and productivity. In the next chapter, we are going to look at how one can protect a web application using the OpenSSO Server and OpenSSO policy agents. This chapter will deal with the authorization policies and configuring policy agents to protect a sample web application.

[ 153 ]

Protecting a Simple Web Application to Provide SSO In this chapter, let us see how the customer can protect their web application using the OpenSSO Policy agents in order to provide Single Sign-On (SSO) capability. SSO is an access-control mechanism that enables users to log in and access multiple applications without having to log in again. With fewer login credentials to create, memorize, apply, and maintain, users and IT both benefit by saving time and effort. There are three types of SSO that are possible with OpenSSO. They are as follows: •

Same-domain SSO or simply SSO is applied only to a single Domain Name System (DNS) domain.

•

Cross-domain SSO (CDSSO) is applied to multiple domains within the same organization. With CDSSO in place, a user needs to log in only once and can then seamlessly access resources in different domains. After authentication, when a user requests a resource in another domain, the CDSSO mechanism transparently transfers from the first domain to the intended destination, an encrypted identity token affirming the user's authentication status. The destination domain then uses the token to build credentials for that user in its own cache. The token does not contain password information—hence another plus for security.

•

Federation is applied to domains across organizations, thanks to an industry standards-based method for sharing and managing identity data. By forming trust relationships, organizations can internally integrate applications from various departments and offer secure SSO services across the board. The same scenario works for services from external trusted partners. The standards in question include those developed by the Organization for the Advancement of Structured Information Standards (OASIS) and the Liberty Alliance Project.

Protecting a Simple Web Application to Provide SSO

The following table lists as examples the domain names for the three types of SSO: SSO Type Same-domain SSO CDSSO Federation

Policy Agent Host agent1.sales.xyz. com agent1.marketing. xyz.com agent1.abc.com

OpenSSO Server Host opensso1.sales.xyz.com opensso1.sales.xyz.com opensso1.xyz.com

You can enforce SSO, CDSSO, and federation with OpenSSO. The procedure in this chapter describes how to achieve same-domain SSO only with that software.

OpenSSO Policy Framework

The Policy agents work in association with the OpenSSO Policy component often called the Policy Decision Point (PDP). Before getting into the core discussions, let us explore a generic use case when someone needs to protect their application. In general, every business has resources and services that they want to protect, manage, and monitor. These businesses need to control the resource usage and access. Businesses control the resource use and access by setting up policies that administer who can do what to which resources, when, and how. OpenSSO can help businesses set up policies for controlling access to their resources, administer the policies, and authorize access to their resources based on their policies. The whole thing is orchestrated by using the Policy Evaluation component and a Policy Enforcement component. Policy Service in the OpenSSO system provides the functionality of a Policy Administration Point (PAP) and Policy Decision Point (PDP). Like any other service this is defined using an XML file that conforms to sms.dtd. As a PAP, Policy Service implements the functionality to define Policies. A Policy in the OpenSSO system comprises Rule(s), Subject(s), Condition(s), Referral(s), and ResponseProvider(s). Subject, Condition, Referral, and ResponseProvider are interfaces and allow for different implementations, making the policy framework easily customizable and extensible. A Rule specifies the service type, resource, applicable actions, and applicable values for actions such as "allow" or "deny". Action could also take nonboolean values. A Subject identifies a collection of principles the policy applies to. Some examples are LDAP roles and groups. Condition specifies additional checks that need to be satisfied for the policy to be applicable. Some examples are time of access and the authentication level at which the user has authenticated. ResponseProvider provides some named attribute values that are included in policy decision. A Policy Enforcement Point (PEP) would typically pass these attributes to the applications it protects. The protected application could use these attributes to personalize the application behavior or use them to enforce fine-grained access control. [ 156 ]

Chapter 6

A Referral policy is like a normal policy except the evalution of the policy is delegated to the respecitve realm to which the referal is set to. It could be a sub-realm or peer realm. As a PDP, Policy service implements the functionality to compute policy decisions. Policy service looks up applicable policies and evaluates policy decisions, which is applicable to a request by a principal on a resource, taking into account the environment parameters associated with the request. A policy decision wraps the applicable action values, policy advices, and response attributes. Policy advices are hints to PEP on some additional action that may be taken by PEP. One sample use of policy advice is to let PEP know the required authentication level to access a resource. A policy decision also has an "expires at" timestamp. A policy framework would not return an expired policy decision to clients. A PEP that caches a policy decision should not use the decision beyond its "expires at" timestamp. The Policy Store is a logically centralized but possibly physically distributed store of the policy component that ensures integrity and consistency of the policies. As there can be several evaluators and policy administrators running simultaneously, they all need to cooperate well so that a change to the policy by one of the policy administrators is appropriately propagated in a timely manner to all the other policy administrators and evaluators. To enable this, the policy store supports change notifications. The policy store's out-of-the-box configuration uses the embedded store, which is based on OpenDS LDAP server. One can use the Oracle Directory Server Enterprise Edition as the policy store for a highly available environment. OpenSSO Policy Agents are provided as add-on components, one for each container type that facilitate the protection of web-based network resources (enterprise applications and services). Policy Agents consume the public APIs and take care of the integration with the specific container such that their presence is largely transparent to the contained protected resources. OpenSSO broadly provides two types of policy agents, Agents for: • •

Web and web proxy servers J2EE agents for Servlet containers and Application servers

Web agents control access to content on web servers and proxy servers. The content that web agents can protect include a multitude of services and web resources based on policies configured by an administrator. When a user points a browser to a URL deployed on a protected web or proxy server, the agent intercepts the request and validates the user's session token, if any exists. Otherwise a login page will be shown, prompting the user for credentials. Upon successful authentication based on the policy decision from the PDP, the individual is either allowed or denied access to the URL. These type of agents are simply a plugin NSAPI for iPlanet web/proxy servers or ISAPI filter for Microsoft IIS servers. [ 157 ]

Protecting a Simple Web Application to Provide SSO

The J2EE agents are meant to protect the web applications that are deployed on Java EE-based Servlet containers and application servers such as the Oracle Weblogic Server. J2EE agents can help to enable role-to-principal mapping for protected Java EE applications with OpenSSO's principals. J2EE agents are implemented as a Servlet filter that need to be included in the web.xml of the application being protected along with an agent realm that is established at the installation time. The agents on the application servers such as IBM WebSphere involve more than just a Servlet filter as it does include the necessary code to set the agents realm and set the Java principal in the container by implementing the appropriate Trust Association Interceptor (TAI). A custom JAR file will be added by the OpenSSO policy agents in the container's classpath during the installation process. One of the key differences between the Web and Java agent is the default protection scope. In the web server the document root is protected on installing the agent, whereas in the Java EE agents it is limited to the web application where the agent filter is included. In this chapter, let us discuss the following: •

Protecting a sample Java application deployed on Tomcat server

•

Passing identity attributes to the protected application via Policy agents

You can use any operating system to perform the instructions given in this chapter, but for ease of use I have used the syntax that is applicable for the Linux operating system. Only Java agents are described in this chapter because installing and configuring web server agents is a trivial process.

Protecting a sample application on Tomcat

In this section, I am going to show you how one can install the policy agents on the Tomcat server and configure the sample application agentsample.war that is shipped with the OpenSSO policy agent. You can download the OpenSSO policy agent for the Tomcat server from the http://www.forgerock.com/downloads. html link. Download the Tomcat server 6.0.20 and configure to an available port. For this exercise the following hosts are used OpenSSO Server

http://opensso.packt-services.net:9090

OpenSSO Policy agents

http://payslip.packt-services.net:7070

[ 158 ]

Chapter 6

Both the server and the agents are running on Apache Tomcat server 6.0.20. Protecting and providing the SSO for a sample Java application requires the following steps: 1. Creating an agent profile. 2. Installing and configuring the agents. 3. Deploying and configuring the Java application. 4. Creating the policies and associated identities. 5. Testing the SSO. 6. Passing the attribute to the agent application.

Creating the agent profile

Once the Tomcat server is configured properly, you can start the policy agents' installer from the location where you have unzipped the binary. Before starting the installer you need to make sure an agent profile is created in the OpenSSO server. There is a custom option that lets the agent installer create the profile dynamically, but for now let us create it manually by using the ssoadm tool. Before starting the agent installer you should first stop the container on which you are planning to install, otherwise you might lose the agent configuration after the container restarts.

The following command can be used to create the agent profile. Every agent requires a profile based on whether it is Java or web server agent. Policy agents themselves authenticate to the server using this profile thereby obtaining the application SSO token. ./ssoadm create-agent -t J2EEAgent -u amadmin -f /tmp/.passwd_of_ amadmin -e / -D agents.attr -b payslip

You might be wondering what goes in the data file mentioned as part of the -D option. This file agents.attr, which is part of the code bundle, consists of various configuration items that are needed to configure the agent and the sample application. The name of the agent profile is payslip. Once you create the agents profile, you can go ahead and install the agents on the Tomcat. It is important that you understand these properties as what they mean and how changing the values impact your deployment. You should be able to find the properties description at the following website http://wikis.sun.com/display/ OpenSSO/agent3properties.

[ 159 ]

Protecting a Simple Web Application to Provide SSO

Installing and configuring the agents

Now unzip the OpenSSO Policy Agents 3.0 for Apache Tomcat into a location that has read and write access in the file system. Upon unzipping the tomcat_ v6_agent_3.zip file, you can find the script j2ee_agents/tomcat_v6_agent/ bin/agentadmin, this will not have the execute permissions, you need to give the permissions by executing the command: chmod +x j2ee_agents/tomcat_v6_agent/bin/agentadmin

Now you can invoke the installer to configure the policy agents 3.0 for Apache Tomcat: ./agentadmin --custom-install --useResponse /tmp/resp

This will return success if no errors occur during the configuration. You might be wondering what is there in the user response file /tmp/resp. It contains the container-specific and OpenSSO server details including the policy agent profile data: # Agent User Response File CONFIG_DIR= /export/ssouser/AGENTS30/apache-tomcat-6.0.20/conf CATALINA_HOME= /export/ssouser/AGENTS30/apache-tomcat-6.0.20 AM_SERVER_URL= http://opensso.packt-services.net:9090/opensso/ AGENT_URL= http://payslip.packt-services.net:7070/agentapp AGENT_ENCRYPT_KEY= S4cA0JFeTMs/a6qsjm4uvv68fG2XFQAd AGENT_PROFILE_NAME= payslip AGENT_PASSWORD_FILE= /tmp/pass CREATE_AGENT_PROFILE_NAME= false AGENT_ADMINISTRATOR_NAME= amadmin AGENT_ADMINISTRATOR_PASSWORD_FILE= /tmp/.passwd_of_amadmin

Deploying and configuring the Java application

Our goal is to protect a Java web application deployed on the Tomcat container. For this purpose, let us use the sample web application that comes with the policy agents. This application is located under the directory, sampleapp/dist with the name agentsample.war. This is a specialized web archive, developed and tested by the OpenSSO team. It is an application that exhibits the features of Java EE agents including the programmatic security role mapping and attribute fetch from the OpenSSO server. You can just copy the agentsample.war to the Tomcat server's webapps directory. This will automatically deploy the application, and it will be available with the context root of /agentsample.

[ 160 ]

Chapter 6

Now you should be able to access the application by entering http://payslip. packt-services.net:7070/agentsample/public/welcome.html. On hitting Enter you will see a page like the one shown in the following screenshot:

Creating policies and associated identities

Let us now focus on the configurations that are required in both, the server side and the agents profile side. For your information the agents' configurations are centralized and stored in the server's configuration data store. Let us spend some time in understanding the properties files that are created in the agents' host as part of the agent installation. Upon successful installation, you would find OpenSSOAgentBootstrap.properties and OpenSSOAgentConfiguration. properties under the /j2ee_agents/tomcat_v6_ agent//config directory.

[ 161 ]

Protecting a Simple Web Application to Provide SSO

The OpenSSOAgentBootstrap.properties file provides the initialization parameters for the OpenSSO policy agents to determine whether they are using a local configuration or remote configuration. Depending on that it bootstraps itself. It contains the OpenSSO server naming service, agent profile name, and password. These details will be used to contact the OpenSSO server in order to decide whether to use the local or remote configuration. The other file, OpenSSOAgentConfiguration. properties will only be consulted when the agents are running in local configuration mode. It means all the agent properties are stored locally in this file. Note that this will be generated even in the centralized agents' configuration, but will not be used until the agents' configuration is set to local file-based. In the centralized agent configuration mode, all the changes to the agent properties happen at the OpenSSO server side using UI or ssoadm tool, let us use the ssoadm to configure the policies and other associated configurations. The instructions to configure this web application are located under the same directory where the WAR file is located. All the items mentioned in the readme.txt under the Installing and configuring the agents section are already taken care of as part of the agent profile creation. So there is nothing that needs to be done in this section. The rest of the policy provisioning and users/groups creation will be taken care of by the following script: #!/bin/sh PATH=/export/ssouser/TOMCAT/opensso-9090/ssoadm/opensso/bin:$PATH export PATH FILE=/tmp/myuser.$$ PASS_FILE=/tmp/.passwd_of_amadmin echo "secret12" > $PASS_FILE chmod 400 $PASS_FILE ROLE=Group ssoadm set-realm-svc-attrs -u amadmin -f $PASS_FILE -s sunIdentityRepositoryService -e / -a sunIdRepoAttributeValidator=class =com.sun.identity.idm.server.IdRepoAttributeValidatorImpl sunIdRepoAtt ributeValidator=minimumPasswordLength=2 USERS="andy bob chris dave ellen frank gina" for usr in $USERS do echo "create-identity -i $usr -t User -e / -a userpassword=${usr} cn=${usr} sn=${usr} " >> $FILE done ssoadm do-batch -u amadmin -f $PASS_FILE -D $FILE ssoadm create-identity -i employee -t $ROLE -u amadmin -f $PASS_FILE -e / ssoadm create-identity -i manager -t $ROLE -u amadmin -f $PASS_FILE -e / ssoadm create-identity -i everyone -t $ROLE -u amadmin -f $PASS_FILE -e / [ 162 ]

Chapter 6 ssoadm create-identity -i customer -t Group -u amadmin -f $PASS_FILE -e / #customer ssoadm add-member -i customer -t Group -m chris -y User -u amadmin -f $PASS_FILE -e / ssoadm add-member -i customer -t Group -m ellen -y User -u amadmin -f $PASS_FILE -e / #Manager ssoadm add-member -i manager -t $ROLE -m chris -y User -u amadmin -f $PASS_FILE -e / ssoadm add-member -i manager -t $ROLE -m andy -y User -u amadmin -f $PASS_FILE -e / ssoadm add-member -i manager -t $ROLE -m bob -y User -u amadmin -f $PASS_FILE -e / #employee USERS="andy bob chris dave ellen frank " for mem in $USERS do ssoadm add-member -i employee -t $ROLE -m $mem -y User -u amadmin -f $PASS_FILE -e / done #everyone USERS="gina andy bob chris dave ellen frank " for mem in $USERS do ssoadm add-member -i everyone -t $ROLE -m $mem -y User -u amadmin -f $PASS_FILE -e / done #create the agent profile, you can uncomment the following line if you want to create everything at one shot #ssoadm create-agent -t J2EEAgent -u amadmin -f $PASS_FILE -e / -D agents.attr -b payslip #create Policy ssoadm create-policies -e / -X pol.xml -u amadmin -f $PASS_FILE

This script will create the necessary policies,users and groups. It will also add the group memberships accordingly as described in the readme.txt file that comes with the sample application. There is one more that I need to describe is the policy xml file pol.xml that creates all the necessary policies for the sample application to work. The contents of the pol.xml is supplied as part of the code bundle.

[ 163 ]

Protecting a Simple Web Application to Provide SSO

Testing the SSO

What we have just completed is the configuration portion of the application, Policy Agents, and the Policy server which is OpenSSO. In the agent sample application, the agent Servlet filter is inserted so that it will protect the application by redirecting to the authentication service if no valid session exists. There is one more crucial configuration that is preinserted while creating the application that is the Java security role mapping. This is done in the web.xml of the application as shown in the following code; the first part shows the agents filter, and the next part deals with the role mapping: OpenSSO J2EE Policy Agent Sample Application An application to demonstrate the features of J2EE Policy Agents Agent com.sun.identity.agents.filter.AmAgentFilter Agent /* REQUEST INCLUDE FORWARD ERROR

The role mapping is done as follows in the web.xml of the agents sample application: SecurityAwareServlet SecurityAwareServlet com.sun.identity.agents.sample. SecurityAwareServlet MANAGER_ROLE id=manager,ou=group,dc=opensso,dc=java,dc=net EMPLOYEE_ROLE id=employee,ou=group,dc=opensso,dc=java,dc=n et

[ 164 ]

Chapter 6

If you are using a different user suffix, other than dc=opensso, dc=java, dc=net then you should update this web.xml with your suffix and rebuild the agentsample. war file as described in the readme.txt of the sample application. The sample application is a collection of servlets and JSPs that demonstrate the salient features of the Java policy agent. These features include SSO, web-tier declarative security, URL policy evaluation, and attribute retrieval from the OpenSSO server.

Download from Wow! eBook

Now you can test the sample application; for the Single Sign-On, test the declarative security by means of Java security role mapping. From the welcome page you can select the links as appropriate. Let us say we want to select the J2EE Declarative Security link. By clicking on this link you can see the following screenshot:

[ 165 ]

Protecting a Simple Web Application to Provide SSO

Now click on the Invoke the Protected Servlet, this will redirect to the OpenSSO server for authentication and authorization. Provide the credential of user andy (password is andy). After the successful authentication, the page will show that the user andy is a manager. Hence, the authorization was allowed. This aligns with our policy that we have set in the server. Now click on the other link named J2EE Security API, this will automatically get authorization because we have already authenticated as the user andy who belongs to the role manager. Note that the J2EE Declarative Security and J2EE Security API are protected and authorized only for users who are members of the role manager. You can see a page, something similar to the following screenshot after clicking on the J2EE Security API link.

Remember, we have authenticated to the J2EE security link, so we do not need to authenticate again for the J2EE Security API link, as both can invoke different servlets in the backend in a single login, though it is a much simplified version of the typical usecase. In a customer deployment, both kinds of applications could be deployed on two different containers with different profiles serving the agents, as long as they are located in the same DNS domain and served by the same OpenSSO server. On the other hand, with the same session (as user andy) if you try to access the URL Policy Enforcement link, the authorization will fail to access the resource because this link is authorized only for the users who belong to the group customer, so it is the expected behavior. Now log out from the OpenSSO server and log in back as the user chris, and you will be able to access URL Policy Enforcement link, as chris is authorized to access this resource.

[ 166 ]

Chapter 6

Fetching user profile attributes

In most of the application deployments the application administrator wants to customize the interface based on the authenticated users' profile attributes. In order to achieve this, there must be a way to convey the attribute information securely to these remote applications. OpenSSO Policy Agents can obtain the authenticated identity's attributes as well as the resource-specific attributes by the following means: •

Setting in as HTTP header / request parameters

•

Setting in the browser cookie as name value pairs

In this part of the section, only the HTTP header option is discussed, as the rest of the options follow the same pattern. The end application protected by the agents can obtain the authenticated identity's attributes as the HTTP header name value pairs in the following three ways: •

Retrieve from authenticated identity's profile

•

Retrieve from authenticated identity's session

•

Retrieve from policy resource response providers

Whether you want to obtain the values as a cookie or HTTP header is determined by the agent profile configuration. The following properties control these options: com.sun.identity.agents.config.profile.attribute.fetch.mode=HTTP_ HEADER com.sun.identity.agents.config.profile.attribute.mapping[cn]=payslipcn com.sun.identity.agents.config.profile.attribute. mapping[objectclass]=payslip-objectclass com.sun.identity.agents.config.profile.attribute.mapping[sn]=payslip-sn

From the admin console it can be updated from the agents tab as shown in the following screenshot:

[ 167 ]

Protecting a Simple Web Application to Provide SSO

After updating, make sure you save the changes. I takes effect right away as these properties are hot swap enabled. Now, go back and access the Show HTTP Headers page. It will show you the values of the user's objectclass, sn, and cn attributes as shown in the following screenshot, for the authenticated user andy:

In the same manner one can obtain the user's session and response attributes defined as part of the policy.

Summary

In this chapter, we have covered the basic principles of protecting a web application and providing a single log in for multiple resources. I have used the sample application that gets shipped with the OpenSSO Policy agents 3.0 for not only its ease of use but its feature richness. The application has extensive features to show about the agents. There are other features such as cross domain SSO that are not covered here as the scope of the chapter does not permit it. However, you should be able to find lots of resources on the Internet to make yourself knowledgeable in those areas. We have also covered how the remote application can obtain the user attributes in a secure manner over the wire. Typically, you are advised to use the transport security layer while retrieving the attributes as part of the HTTP headers to alleviate the security concerns. In the next chapter, you will be introduced to the concepts of software as a service-based application (SaaS) and how to integrate them with OpenSSO based infrastructure for SSO. You will be given step-by-step instructions to configure the Google Apps and Salesforce application to integrate with the OpenSSO Identity provider using the SAMLv2 protocol.

[ 168 ]

Integrating Salesforce and Google Apps The software-as-a-service (SaaS) vendors are growing at a steady pace, which shows that customers are relying more and more on the hosted services than building in-house applications. SaaS differentiates itself from the "On Premise" software by avoiding the need to purchase and maintain the computer hardware and related infrastructure to run an application. The only infrastructure required is a personal computer to run the software and sufficient network connectivity to access the Internet. The SaaS-based applications are proven to be highly available and scalable; specifically Salesforce, as they proved to be a leader in selling their applications hosted on their data centers. Likewise, Google is also providing hosted mail services for small business owners and educational institutions. For all of these applications the consumer is from the end user organizations. The users connect to the Internet to access these on-demand applications. The identity information of these users must be protected appropriately. This can be done by the organization itself by securing and storing the data or delegating them as they do not host any services, except the user identity storage. In this chapter, let us discuss how the OpenSSO can be configured as the identity provider to provide authentication services for the following SaaS-based hosted applications: •

Salesforce.com

•

Google Apps

Integrating Salesforce and Google Apps

Configuration of the metadata details for these applications are made very intuitive by means of a workflow-like interface in OpenSSO that will be discussed in the next few sections. This chapter will not address the concepts of federation or the protocols such as SAML. If you are interested in learning more about them, please point your browser to http://docs.sun.com/app/docs/doc/820-5986?l=en.

Integrating OpenSSO with Salesforce applications

Now, it is simple to use OpenSSO as an identity provider for SSO with Salesforce. com applications using the SAMLv2 protocol. Out-of-the-box OpenSSO supports an easy-to-use workflow feature that enables the customers to integrate Salesforce. com applications to their existing authentication infrastructure. There are multiple ways to achieve the SSO with Salesforce.com. The IDP users' attributes can be sent to the Service Provider (SP) in one of the following ways: •

As an attribute statement in the SAML assertion

•

As a nameID element in the SAML assertion subject statement

In the same manner, service provider at salesforce.com can use any of these two options for its local attribute that is used to perform the SSO. It can be one of these: •

Salesforce.com user's Federation ID attribute

•

Salesforce.com user's user ID

In this chapter, let us discuss the steps for configuring the identity provider to send the attribute value as an attribute statement in the SAML assertion. The service provider at Salesforce.com is configured to use the Federation ID attribute to match the identity provider user's attribute. Integrating the Salesforce CRM application with the OpenSSO authentication SSO infrastructure involves a certain metadata exchange between the two entities. The following several subsections are devoted to explaining in detail this procedure. Please follow them closely in order to avoid any errors while performing SSO.

[ 170 ]

Chapter 7

Configuring hosted identity provider and circle of trust

As the OpenSSO acts as the identity provider, one has to configure the OpenSSO as the hosted identity provider and create the circle of trust to which the remote service provider, that is the CRM application hosted by Salesforce.com , will belong. To perform this step log in as the top level admin to the OpenSSO and access the Common Tasks | Create Hosted Identity Provider link. In the subsequent page you will see a couple of text boxes that need to be filled in. Fill in those details as shown in the following screenshot:

Once you complete this process, you will be shown a page to configure the Salesforce.com CRM. For the signing and encryption, the default test certificate keystore is used. You can create custom keystores using the keytool command as described in Chapter 2.

[ 171 ]

Integrating Salesforce and Google Apps

Configuring OpenSSO metadata for Salesforce.com

Once you click on the Configure Salesforce CRM application link, then you will be guided to create an attribute mapping between the identity provider account (in this case it is OpenSSO) and the service provider's account (in this case Salesforce application). In the Salesforce.com account there is a special attribute called Federation ID, this attribute will be consulted while performing the SSO with the OpenSSO account. In this example, we are planning to send the identity provider account's telephoneNumber as part of the assertion, so that the users at the Salesforce.com could use this information to perform the SSO. Essentially SAMLv2 SSO will be successful if the authenticated (at the OpenSSO) identity's telephoneNumber matches uniquely with a user's Federation ID attribute at the Salesforce.com application domain.

In this case the attribute telephoneNumber is passed on to SP (Salesforce.com) in the assertion statement as ATTR_PHONE. The value of this attribute will be picked up and matched with one of the Salesforce.com user's Federation ID attribute. A match would trigger a successful SSO. At this point you will be shown a certificate value which needs to be exported to the Salesforce.com domain. In turn a login URL that would be provided by the Salesforce.com domain would have to be loaded into the OpenSSO.

[ 172 ]

Chapter 7

There will be a sequence of steps that need to be followed. In short this is what you need to do: 1. Click the Salesforce CRM link to open the application's Single Sign-On set up page in a new browser window. 2. Log in with your administrator username and password. Only the application administrators can perform this step not the end user. The end user cannot choose this option unless the Salesforce application admin enable SSO between OpenSSO and Salesforce. 3. Click on the Setup link at the top of the Salesforce landing page. 4. Click on Single Sign-On Settings, under Administration Setup | Security Controls on the left side of the Salesforce page. 5. Click on the Edit button under Single Sign-On Settings. 6. Check the SAML Enabled box. 7. Choose SAML Version as 2.0. You can fill in the rest of the details as shown in the following screenshot:

[ 173 ]

Integrating Salesforce and Google Apps

As you can see the attribute ATTR_PHONE is being mapped to the local Salesforce.com users attribute. After completing this configuration you can save the changes. After saving, a summary page will be rendered as shown in the following screenshot:

As you can see it contains the salesforce login URL, which is critical information that has to be copied to the OpenSSO salesforce CRM configuration page (refer to step 16 in the following screenshot) to finish the configuration procedure. This completes all the metadata configuration part of the SSO process. In order to successfully SSO, one should have a user name in both OpenSSO and in Salesforce side. The next section will add the users in OpenSSO (identity provider) and Salesforce (service provider):

Configuring users for Salesforce.com

In order to successfully verify the SAMLv2 SSO, you need to configure at least one user in each provider side. In a typical customer deployment, user identity provisioning could be done using a very well defined workflow process. There are many commercial tools available to achieve these kinds of provisioning tasks.

[ 174 ]

Chapter 7

In OpenSSO, which is the identity provider, we are planning to use the identity named demo. One of the key requirements for SSO to be successful is that the attribute value of telephoneNumber should match with one of the Salesforce.com user's Federation ID attribute.

At the Salesforce service provider, create an account with an appropriate value for the Federation ID attribute so that it could be used for SSO with the OpenSSO account. Let us now log in to the CRM application at the saleforce.com (SP) side to configure the user so that both can SSO using the SAMLv2 protocol. At the service provider side, let's use [email protected] as the user account name. Again let us remember the fact that the IdP-side user's telephoneNumber is mapped to the Federation ID attribute of the SP-side user account. As you can view in the following screenshot, the Federation ID attribute value is matching with the IDP-side user account demo's telephone number, 925-449-0234.

[ 175 ]

Integrating Salesforce and Google Apps

Verifying the SSO

Now we are all set to verify the SSO between the identity provider, which is hosted by OpenSSO and the CRM application hosted by the service provider Salesforce. com. This can be achieved by using the following URL: http://opensso.packt-services.net:9090/opensso/idpssoinit?NameIDFor mat=urn:oasis:names:tc:SAML:2.0:nameid-format:transient&metaAlias=/ idp&spEntityID=https://saml.salesforce.com&binding=urn:oasis:names:tc :SAML:2.0:bindings:HTTP-POST

When you access the previous URL (often termed as IdP initiated SSO), you will be asked for authentication at the OpenSSO side. Use demo as the username with its password changeit . Upon successful authentication it will redirect to the Salesforce.com CRM application logged on as [email protected]. This confirms the SSO integration as you were not asked to enter the password for the user indira.thangasamy at the Salesforce.com .

The following is the excerpt from the actual SAMLv2 response: c1ROyF p+7k3YsQETdF9UasuP8fzk [ 176 ]

Chapter 7 https://saml.salesforce.com urn:oasis:names:tc:SAML:2.0:ac: classes:PasswordProtectedTransport 925-449-0234

In the SAML assertion just given the attribute is a statement that contains the demo user's telephoneNumber attribute (mapped to ATTR_PHONE) value. This value will be matched with the Federation ID attribute of the Salesforce.com account indira. [email protected] to establish the Single Sign-On session.

Integrating with Google Apps

Google Apps is another hosted application platform which is getting increasingly popular in the commercial market as well as in educational institutions, as it is being offered free of cost to the non-profit organizations with up to a certain number of users. It comes with two types of licenses and is associated with some feature differentiators for premier and standard editions. Only premier customers are offered SSO solutions with SAML compliant vendors. If you are running the standard edition, then you will not be able to use this feature as part of your Google Apps and OpenSSO Single Sign-On capability. The procedure for integration of Google Apps with OpenSSO is pretty much similar to the Salesforce.com hosted application integration. So there isn't much that needs to be explained in this section. I will be including the appropriate screenshots so that you can validate your steps along the way. Unlike the Salesforce CRM application integration, Google Apps relies on the usernames being identical on both sides of providers. It means that the username that is being used at the identity provider side must uniquely match the username at the Google Apps-side in order for SSO to be successful. Note that passwords don't necessarily need to be the same.

[ 177 ]

Download from Wow! eBook

Integrating Salesforce and Google Apps

Configuring the hosted identity provider

In this use case scenario, the OpenSSO will be acting as the identity provider for the Google applications. You should create a circle of trust by invoking the Configured Hosted Identity Provider link from the Common Tasks. This step is very intuitive as shown here:

Once you finish this process you will be taken to a landing page where the Google Apps configuration task is. This task will generate all the required URLs and the certificate that will be required to configure the SSO at the Google Apps side.

[ 178 ]

Chapter 7

The domain name entered here is the key information for the Google Apps to append a proper issuer name in the SAML request. This works in association with another parameter in the Google Apps SSO service configuration.

Configuring SSO parameters at Google Apps

Once you enter the Google Apps primary domain-related parameter, the next step will generate the certificate and the list service end points, as shown in the preceding screenshot. At this point log into our packt-services.net domain as the administrative user, as configuration of SSO parameters requires administrative rights.

[ 179 ]

Integrating Salesforce and Google Apps

You should be able to cut and paste the service URL end points as shown in the preceding screenshot. If this step is done without encountering any errors, then the configuration process is pretty much done.

Configuring users for Google Apps

In order to perform SSO between the identity provider (in this case, OpenSSO) and the service provider (the Google Apps), we need to provision users on both sides so that we can correlate both of them in some means. Google Apps requires that the login name of the user identity (of the IdP) should match with its account login name (SP) in order to establish SSO. So there is no separate attribute value required to be sent as part of the assertion; nevertheless, the IdP can optionally send attributes to the service provider. We use jdoe as the login name on both sides as shown in the following screenshot. As you can see the universal ID is jdoe.

Let us look at the Google Apps-side accounts. We have two user accounts—the administrative user and the user, jdoe, who will participate in the SSO process with IdP OpenSSO.

[ 180 ]

Chapter 7

Verifying SSO

Now we are all set to verify the SSO between Google Apps and the OpenSSO by accessing the hosted domain http://mail.packt-services.net. When users access this URL (often termed as SP initiated SSO, because the sign on process is being initiated by the service provider, Google Apps) they will be redirected to the OpenSSO for authentication. After a successful authentication they will be sent back to their e-mail inbox. On accessing the http://mail.packt-services.net an OpenSSO login page will be presented as shown in the following screenshot:

[ 181 ]

Integrating Salesforce and Google Apps

After successful authentication, user jdoe will be redirected to his Gmail inbox. This verifies the successful SSO between OpenSSO and Google Apps. As you can see there is no authentication requested at the Google Apps side because the login name jdoe is identical in both cases along with the SAML assertion sent by the IdP OpenSSO.

This completes the OpenSSO integration with Google Apps for Single Sign-On using the SAMLv2 protocol. Here are some excerpts from the SAML v2 response sent by the IdP. The subject is jdoe and the audience is specific to the Google App domain packt-services.net not just Google: jdoe google.com/a/packt-services.net urn:oasis:names:tc:SAML:2.0:ac: classes:PasswordProtectedTransport [ 182 ]

Chapter 7

Summary

In this chapter, we have covered extensively the idea behind the SaaS-based applications and how those applications can be integrated with the OpenSSO identity provider environment. We have specifically discussed the detailed procedures for integrating the Salesforce.com applications and hosted Google Apps. It is worth noting that Google Apps' standard edition cannot be used with OpenSSO integration as the standard edition does not permit the SSO configurations. In the next chapter I will take you through the various user identity stores configuration and customization. You will be able to find a procedure to configure the OpenLDAP server as the user identity store along with the necessary schema files.

[ 183 ]

Identity Stores In the previous chapters we have extensively called out the various identities including user, group, and role objects in the examples. All these identities must be stored in a backend data repository in order to be accessed by OpenSSO. It is worth remembering that this identity store is different from the configuration store (policy store). The Identity Repository framework provides interfaces that will be used by OpenSSO services such as Authentication, Authorization, and Federation to manipulate identity configuration attributes along with certain service configuration values such as the agent profiles, even though the agent profiles are stored in the configuration store. The Identity Repository framework has a utility class that provides interfaces to manage service configuration attributes of users, roles, and agents per realm. Additionally, it provides interfaces to manage generic attributes for identity objects such as realms, groups, roles, users, and agents. There are Service Provider Interface (SPI) plugin interfaces in the Identity Repository framework to configure a new Identity Repository. Each SPI plugin would have a corresponding service XML schema file defining its configuration attributes as a subschema. In this chapter, you will be able to learn the following topics: •

Identity Repository schema

•

Types of identity stores supported

•

Caching and notification

•

Supported identity stores

•

Multiple identity stores

•

Extending schema for OpenLDAP Identity Repository schema

Identity Stores

Like any other service, the Identity Repository service is also defined using an XML file named idRepoService.xml that can be found in /config/xml. In this file one can define as many subschema as needed. By default, the following subschema names are defined: •

LDAPv3

•

LDAPv3ForAMDS

•

LDAPv3ForOpenDS

•

LDAPv3ForTivoli

•

LDAPv3ForAD

•

LDAPv3ForADAM

•

Files

•

Database

However, not all of them are supported in the version that has been tested while writing this book. For instance the files, LDAPv3, and Database subschema are meant to be sample implementations. One can extend it for other databases, keeping this as an example. The rest of the sub configurations are all well tested and supported. One of the Identity Repository types Access Manager Repository is missing from this definition, as it is a manual process to add it into the OpenSSO server. That is something which will be detailed later in this chapter. It is also called a legacy SDK plugin for OpenSSO. The Identity Repository framework requires support for logging service and session management to deliver its overall functionality.

Identity store types

In OpenSSO, multiple types of Identity Repository plugins are implemented including the following: •

LDAPv3Repo

•

AgentsRepo

•

InternalRepo/SpecialRepo

•

FilesRepo

•

AMSDKRepo

Unlike the Access Manager Repository plugin, these are available in a vanilla OpenSSO server. So customers can readily use it without requiring to perform any additional configuration steps. [ 186 ]

Chapter 8

LDAPv3Repo: Is the plugin that will be used by customers and the administrators quite frequently as the other types of plugin implementations are mostly meant to be used by OpenSSO internal services. This plugin forms the basis for building the configuration for supporting various LDAP servers including Microsoft Active Directory, Active Directory Application Mode (ADAM/LDS), IBM Tivoli Directory, OpenDS, and Oracle Directory Server Enterprise Edition. There are subschema defined for each of the recently mentioned LDAP servers in the IdRepo service schema as described in the beginning of this section. For more specific configuration details for each of the LDAP servers, refer to the specific section of this chapter. AgentsRepo: Is a plugin that is used to manage the OpenSSO policy agents' profiles. Unlike the LDAPv3Repo, AgentsRepo uses the configuration repository to store the agent's configuration data including authentication information. Prior to the Agents 3.0 version, all agents accessing earlier versions of OpenSSO such as Access Manager 7.1, had most of the configuration data of the agents stored locally in the file system as plain text files. This imposed huge management problems for the customers to upgrade or change any configuration parameters as it required them to log in to each host where the agents are installed. Besides, the configuration of all agents prior to 3.0 was stored in the user identity store. In OpenSSO the agent's profiles and configurations are stored as part of the configuration Directory Information Tree (DIT). The AgentsRepo is a hidden internal repository plugin, and at no point should it be visible to end users or administrators for modification. SpecialRepo: In the predecessor of OpenSSO the administrative users were stored as part of the user identity store. So even when the configuration store is up and running administrators still cannot log in to the system unless the user identity store is up and running. This kind of limits the customer experience especially during pilot testing and troubleshooting scenarios. To overcome this, OpenSSO introduced a feature wherein all the core administrative users are stored as part of the configuration store in the IdRepo service. All the administrative and special user authentication by default uses this specialrepo framework. It may be possible to override this behavior by invoking module based authentication. SpecialRepo is used as a fallback repository to get authenticated to the OpenSSO server. SpecialRepo is also a hidden internal repository plugin. At no point, should it be visible to end users or administrators for modification. FilesRepo: Is no longer supported in the OpenSSO product. You can see the references of this in the source code but it cannot be configured to use flat files store for either configuration data or user identity data.

[ 187 ]

Identity Stores

AMSDKRepo: This plugin has been made available to maintain the compatibility with the Sun Java System Access Manager versions. When this plugin is enabled the identity schema is defined using the DAI service as described in the ums.xml. This plugin will not be available in the vanilla OpenSSO server, the administrator has to perform certain manual steps to have this plugin available for use. In this plugin, identity management is tightly coupled with the Oracle Directory Server Enterprise Edition. It is generally useful in the co-existence scenario where OpenSSO needs to co-exist with Sun Access Manager. In this book wherever we refer to "Access Manager Repository plugin" it means refer to AMSDKRepo. Besides this there is a sample implementation for the MySQL-based database repository available as part of the server default configuration. It works; however, it is not extensively tested for all the OpenSSO features. You can also refer to another discussion on the custom database repository implementation at this link: http://

www.badgers-in-foil.co.uk/notes/installing_a_custom_opensso_identity_ repository/.

Caching and notification

For the LDAPv3Repo, the key feature that enables it to perform and scale is the caching of results set for each client query, without which it would be impossible to achieve the performance and scalability. When caching is employed there is a possibility that clients could get stale information about identities. This can be avoided by keeping the cache cleaned up periodically or having an external event dirty the cache so new values can be cached. OpenSSO provides more than one way to tackle this caching and notification. There are a couple of ways in which the cache can be invalidated and refreshed. The Identity Repository design relies broadly on two types of mechanisms to refresh the IdRepo cache. They are: •

Persistent search-based event notification

•

Time-to-live (TTL) based refresh

Both methods have their own merits and can be enabled simultaneously, and it is recommended. This is to handle the scenario where a network glitch (which could cause a packet loss) might have caused the OpenSSO server to miss some change notifications. The value of TTL purely depends on the deployment environment and end user experience.

[ 188 ]

Chapter 8

Persistent search-based notification

The OpenSSO Identity Repository plugin cache can be invalidated and refreshed by registering a persistent search connection to the backend LDAP server provided the LDAP server supports the persistent search control. The persistent search (http:// www.mozilla.org/directory/ietf-docs/draft-smith-psearch-ldap-01.txt) control 2.16.840.1.113730.3.4.3 is implemented by many of the commercial LDAP servers including: •

IBM (Tivoli Directory)

•

Novell (eDirectory)

•

Oracle Directory Server Enterprise Edition(ODSEE)

•

OpenDS (OpenDS Directory Server 1.0.0-build007)

•

Fedora-Directory/1.0.4 B2006.312.1539

In order to determine whether your LDAP vendor supports a persistent search, perform the following search for the persistent search control 2.16.840.1.113730.3.4.3: ldapsearch -p 389 -h ds_host -s base -b '' "objectclass=*" supportedControl | grep 2.16.840.1.113730.3.4.3

Microsoft Active Directory implements in a different form using the LDAP control 1.2.840.113556.1.4.528. Persistent searches are handled by the max-psearch-count property in the Sun Java Directory Server that defines the maximum number of persistent searches that can be performed on the directory server. The persistent search mechanism provides an active channel through which entries that change (and information about the changes that occur) can be communicated. As each persistent search operation uses one thread, limiting the number of simultaneous persistent searches prevents certain kinds of denial of service attacks. It is quite apparent that a client implementation that generates a large number of persistent connections to a single directory server may indicate that the LDAP protocol may not have been the correct transport. However, horizontal scaling using Directory Proxy Servers, or an LDAP Consumer tier, may assist to spread the load. The best solution, from an LDAP implementation, would be to limit persistent searches. If you have created a user data store against an LDAP server which supports RFC2026, then a persistent search connection will be created with base DN configured in the LDAPv3 configuration. [ 189 ]

Identity Stores

The search filter for this connection is obtained from the data store configuration properties. Though it is possible to listen to a specific type of change event, OpenSSO registers the persistent search connections to receive all kinds of change events. The IdRepo framework has the logic to determine whether the underlying directory server supports persistent searches or not. If not supported it does not try to submit the persistent search. In this case customers may resort to a TTL-based notification as described in the next section. Each active persistent search request requires that an open TCP connection be maintained between an LDAP client (in this case it is OpenSSO) and an LDAP (backend user store LDAP server) server that might not otherwise be kept open. The OpenSSO server that acts as an LDAP client closes idle LDAP connections to the backend LDAP server in order to maximize the resource utilization. If the OpenSSO servers are behind the load balancer or a firewall you need to tune the value of "com. sun.am.event.connection.idle.timeout". If the persistent search connections are made through a Load Balancer (LB) or firewall, then these connections are subject to the TCP timeout value of the respective LB and/or firewall. In such a scenario once the firewall closes the persistent search connection due to an idle TCP timeout, then the change notifications cannot happen to OpenSSO unless the persistent search connection is re-established. Customers could avoid this scenario by configuring the idle timeout for the persistent search connection so that it would restart the persistent search TCP connection before the LB/firewall idle timeout, that way the LB/firewall will not have an idle persistent search connection. The advanced server configuration property "com.sun.am.event.connection. idle.timeout" specifies timeout value in minutes after which the persistent searches will be restarted. Ideally, this value should be lower than the LB/firewall TCP timeout, to make sure that the persistent searches are restarted before the connections are dropped. A value of "0" indicates that these searches will not be restarted. By default the value is "0". Only the connections that are timed out will be reset. You should never set this value to a value lower than the LB/firewall timeout. The delta should not be more than five minutes. If your LB's idle connection timeout is "50" minutes, then set this property value to "45" minutes.

For some reason if you want to disable the persistent search to be submitted to the backend LDAP server, just leave the persistent search base (sun-idrepo-ldapv3config-psearchbase) empty, this will cause the IdRepo to disable the persistent search connection.

[ 190 ]

Chapter 8

Time-to-live based notification

There may be deployment scenarios where persistent search-based notifications may not be possible or the underlying LDAP server may not be supporting the persistent search control. In such scenarios customers can employ the TTL or timeto-live based notification mechanism. It is a feature that involves a proprietary implementation by the OpenSSO server. This feature works in a fashion that is similar to the polling mechanism in the OpenSSO clients where the client periodically polls the OpenSSO server for changes, often called "pull" model. Whereas persistent search-based notifications are termed as "push" model (the LDAP server pushes the changes to the clients). Regardless of the persistent search based change notifications, the OpenSSO server polls the underlying directory server and gets the data to refresh its Identity Repository cache.

TTL-specific properties for Identity Repository cache When the OpenSSO deployment is configured for TTL-based cache refresh, there are certain server-side properties that need to be configured to enable the Identity Repository framework to refresh the cache. The following are the core properties that are relevant in the TTL context: •

com.sun.identity.idm.cache.entry.expire.enabled=true

•

com.sun.identity.idm.cache.entry.user.expire.time=1 (in minutes).

•

com.sun.identity.idm.cache.entry.default.expire.time=1

(in minutes).

The property com.sun.identity.idm.cache.user.expire.time and com.sun. identity.idm.cache.default.expire.time specify time in minutes for which the user and non-user entries such as roles and groups respectively remain valid after their last modification. In other words after this specified period of time elapses, the data for the entry that is cached will expire. At that instant, new requests for these entries will result in fresh reading from the underlying Identity Repository plugins. Suppose the property com.sun.identity.idm.cache.entry.expire.enabled is set to true, the non-user objects cache entries will expire based on the time specified in the com.sun.identity.idm.cache.entry.default.expire.time property. The rest of the user entries objects will be cleaned up based on the value set in the property com.sun.identity.idm.cache.entry.user.expire.time.

[ 191 ]

Identity Stores

Supported identity stores

Identity stores in OpenSSO serves as the key feature for authentication and authorization. These are predominantly Lightweight Directory Access Protocol, or LDAP servers. There are multiple types of LDAP servers tested and certified with OpenSSO as identity stores. Almost all of the market-leading commercial LDAP servers are supported. In this section let us explore how to create and manage identity stores for each type of LDAP server. Each LDAP server has its own sub configuration identifier in the Identity Repository schema definition. The database plugin is only an early access feature; hence, we will not be covering here.

User schema

When a new identity user store is created from the console or CLI, the OpenSSO server creates a configuration entry in its configuration store followed by loading the OpenSSO-specific schema into the corresponding LDAP servers provided. The LDAP user provided (sun-idrepo-ldapv3-config-authid) should have read and write access to the base (sun-idrepo-ldapv3-config-organization_name) distinguished name (DN) and the schema configuration DN. To take advantage of the authentication lockout, password reset, and federation features of OpenSSO, one needs to extend the underlying LDAP servers' schema to accommodate OpenSSO-specific object classes and attributes. This schema extension is done automatically for the supported LDAP servers discussed in this section with exception of OpenLDAP. Even though it is possible to work with these directories without extending the schema, you cannot manage the data store configuration from the OpenSSO administrative console, and the following functionalities will not be available: •

User account lockout in multi-server configuration

•

User account expiry

•

Password reset

•

Extensive federation features such as IDFF PP service

•

User-based authentication, session constraint, success, and failure URLs

[ 192 ]

Download from Wow! eBook

Chapter 8

The specific schema files and associated entries for each directory server will be kept under the /ldif directory. These files are created at the time of the OpenSSO server configuration. These LDIF files will be consumed by the Identity Repository framework either at the time of server configuration or at the point when the checkbox Load schema when saved: is enabled while saving the data store configuration from the administrative console. This option is not available from the ssoadm CLI tool. So just creating the data store does not load the schema into the backend directory server, it adds the schema only when the previously mentioned checkbox is checked. You can safely test a read-only data store when needed. The checkbox is enabled, and you can safely test a read-only data store when needed by disabling this checkbox. Now let us see how each type of data store can be created. As usual this process can be achieved via the administrative console (Access Control | Top Level Realm | Data Stores) or ssoadm CLI tool. As it is trivial from the console, I will show you how to manage the data stores using the CLI tool.

Access Manager Repository plugin

This type of Identity Repository is not available in the out of the box configuration; the administrator has to explicitly configure the server to enable the plugin. The default configuration will support the repository types as shown in the following screenshot:

The Access Manager Repository plugin is also called amSDK or legacy SDK as it provides downward compatibility to work with the existing Sun Access Manager 7.x version deployment identity stores. This repository is tightly coupled with the Oracle DSEE server; hence, will not work with any other LDAP servers. To enable this plugin invoke the following command (there is no console user interfaces for this): ./ssoadm add-amsdk-idrepo-plugin -u amadmin -f /tmp/.passwd_of_amadmin -b dc=opensso,dc=java,dc=net -s ldap://dsee.packt-services.net:4355 -x /tmp/.passwd_of_amadmin -p /tmp/.passwd_of_amadmin -v -a uid -o o -e 'cn=Directory Manager' -m /tmp/.passwd_of_dir_mgr [ 193 ]

Identity Stores

Once this command is successful, you will be able to create amSDK plugin after restarting the server. The list of supported data stores will include the Access Manager Repository plugin as follows:

Creating an Access Manager Repository plugin data store

Access Manager Repository plugin or amSDK data store can be created from a console interface or from CLI (the former is a trivial process). Let us use ssoadm to accomplish this. Here is how you can create the datastore: ssoadm create-datastore -e / -u amadmin -f /tmp/.passwd_of_amadmin -t amSDK -D /tmp/mydata -m datastoreforamsdk

where /tmp/mydata contains the following attributes: sun-idrepo-amSDK-config-copyconfig-enabled=false amSDKOrgName=dc=opensso,dc=java,dc=net sun-idrepo-amSDK-config-people-container-name=ou sun-idrepo-amSDK-config-recursive-enabled=false sun-idrepo-amSDK-config-people-container-value=people sunIdRepoClass=com.iplanet.am.sdk.AMSDKRepo

These attributes can be edited from the console as shown in the following screenshot. As you can see there are no options to change the directory server settings. To change the directory server-related information you need to navigate to Configuration | Server and Sites | Instance | Directory Configuration. From this location you will be able to update the directory server settings.

[ 194 ]

Chapter 8

Now you can start creating user and/or role objects in the new repository. One exception here is that the Load schema when finished does not have any impact, as the schema will be loaded when you invoke the add-amsdk-idrepoplugin subcommand.

Displaying the data store properties

In case you want to view the properties of the data store that you have created, you can leverage the show-datastore sub command as shown in the following: ./ssoadm show-datastore -e / -m datastoreforamsdk passwd_of_amadmin

-u amadmin -f /tmp/.

sunIdRepoNamingAttribute=role=cn sunIdRepoNamingAttribute=user=uid sunIdRepoNamingAttribute=group=cn sunIdRepoNamingAttribute=filteredrole=cn sun-idrepo-amSDK-config-copyconfig-enabled=false amSDKOrgName=dc=opensso,dc=java,dc=net sunIdRepoAttributeMapping= RequiredValueValidator=com.sun.identity.sm.RequiredValueValidator sun-idrepo-amSDK-config-people-container-value=people sun-idrepo-amSDK-config-people-container-name=ou sunIdRepoSupportedOperations=group=read sunIdRepoSupportedOperations=role=read,edit,service sunIdRepoSupportedOperations=user=read,create,edit,delete,service sunIdRepoSupportedOperations=filteredrole=read,edit,service sunIdRepoClass=com.iplanet.am.sdk.AMSDKRepo. sun-idrepo-amSDK-config-recursive-enabled=false [ 195 ]

Identity Stores

This will be handy if you want to view the value of a specific property or to update a specific property for which you don't know the property name. This command will dump all the data store properties.

Updating data store properties

Like any other object, one can update the specific properties of an existing data store using the command line tool, ssoadm. For example: the following command after successful execution will change the property sun-idrepo-amSDK-configrecursive-enabled value from false to true: ./ssoadm update-datastore -e / -m datastoreforamsdk -f /tmp/.passwd_of_ amadmin -u amadmin -a "sun-idrepo-amSDK-config-recursive-enabled=true"

In this manner you can change any property whose value needs to be updated.

Deleting data stores

Finally let us close the loop by showing you how an existing data store can be deleted using the delete-datastores subcommand. ./ssoadm delete-datastores -e / -m datastoreforamsdk -f /tmp/.passwd_of_ amadmin -u amadmin

This will only remove the data store named datastoreforamsdk but will not remove the schema or Access Manager Repository plugin from the server. The sequence of commands given in the following section will remove the schema from the server.

Removing the Access Manager Repository plugin

In case you want to remove the Access Manager Repository plugin from the server, you need to remove the subschema entry that is part of the Identity Repository service and the DAI service. Here is the procedure to remove them in order. There is no other interface to perform these actions: ./ssoadm remove-sub-schema -s sunIdentityRepositoryService -t Organization -a amSDK -u amadmin -f /tmp/.passwd_of_amadmin ./ssoadm delete-svc -s DAI -u amadmin -f /tmp/.passwd_of_amadmin

The one exception here is that the delegation policies will not be removed.

[ 196 ]

Chapter 8

Oracle Directory Server Enterprise Edition

The Oracle Directory Server Enterprise Edition type of identity store is predominantly used by customers and natively supported by the OpenSSO server. It is the only data store where all the user management features offered by OpenSSO is supported with no exceptions. In the console it is labeled as Sun DS with OpenSSO schema. After Oracle acquired Sun Microsystems Inc., the brand name for the Sun Directory Server Enterprise Edition has been changed to Oracle Directory Server Enterprise Edition (ODSEE). You need to have the ODSEE configured prior to creating the data store either from the console or CLI as shown in the following section.

Creating a data store for Oracle DSEE

Creating a data store from the OpenSSO console is the easiest way to achieve this task. However, if you want to automate this process in a repeatable fashion, then using the ssoadm tool is the right choice. However, the problem here is to obtain the list of the attributes and their corresponding values. It is not documented anywhere in the publicly available documentation for OpenSSO. Let me show you the easy way out of this by providing the required options and their values for the ssoadm: ./ssoadm create-datastore -m odsee_datastore -t LDAPv3ForAMDS -u amadmin -f /tmp/.passwd_of_amadmin -D data_store_odsee.txt -e /

This command will create the data store that talks to an Oracle DSEE store. The key options in the preceding command are LDAPv3ForAMDS (instructing the server to create a datastore of type ODSEE) and the properties that have been included in the data_ store_odsee.txt. You can find the complete contents of this file as part of the code bundle provided by Packt Publishers. Some excerpts from the file are given as follows: sun-idrepo-ldapv3-config-ldap-server=odsee.packt-services.net:4355 sun-idrepo-ldapv3-config-authid=cn=directory manager sun-idrepo-ldapv3-config-authpw=dssecret12 com.iplanet.am.ldap.connection.delay.between.retries=1000 sun-idrepo-ldapv3-config-auth-naming-attr=uid sun-idrepo-ldapv3-config-users-search-attribute=uid sun-idrepo-ldapv3-config-users-search-filter=(objectclass=inetorgper son) sunIdRepoAttributeMapping= sunIdRepoClass=com.sun.identity.idm.plugins.ldapv3.LDAPv3Repo sunIdRepoSupportedOperations=filteredrole=read,create,edit,delete sunIdRepoSupportedOperations=group=read,create,edit,delete sunIdRepoSupportedOperations=realm=read,create,edit,delete,service sunIdRepoSupportedOperations=role=read,create,edit,delete sunIdRepoSupportedOperations=user=read,create,edit,delete,service

[ 197 ]

Identity Stores

Among these properties, the first three provide critical information for the whole thing to work. As it is evident from the name of the property they denote the ODSEE server name, port, bind DN, and the password. The password is in plain text so you need to remove the password from the input file after creating the data store, for security reasons.

Updating the data store

Like we discussed in the previous section, one can invoke the update-datastore sub command with the appropriate properties and its values along with the -a switch to the ssoadm tool. If you have more properties to be updated, then put them in a text file and use it with the -D option like the create-datastore sub command.

Deleting the data store

A data store can be deleted by just selecting it's specific name from the console. There will be no warnings issued while deleting the data stores, and you could eventually delete all of the data stores in a realm. Be cautious about this behavior, you might end up deleting all of them unintentionally. Deleting data store does not remove any existing data in the underlying LDAP server, it only removes the configuration from the OpenSSO server: ./ssoadm delete-datastores -e / -m odsee_datastore -f /tmp/.passwd_of_ amadmin -u amadmin

Data store for OpenDS

OpenDS is one of the popular LDAP servers that is completely written in Java and available freely under open source license. As a matter of fact the embedded configuration store that is built in the OpenSSO server is the embedded version of OpenDS. It has been fully tested with the OpenDS standalone version for the identity store usage. The data store creation and management are pretty much similar to the steps described in the foregoing section, except the type of store and the corresponding properties' values. The properties and their values are given in the file data_store_opends.txt (available as part of code bundle). Invoke the ssoadm tool with this property file after making appropriate changes to fit to your deployment. Here is the sample command that creates the datastore for OpenDS: ./ssoadm create-datastore -u amadmin -f /tmp/.passwd_of_amadmin -e / -m "OpenDS-store" -t LDAPv3ForOpenDS -D data_store_opends.txt

[ 198 ]

Chapter 8

Data store for Tivoli DS

The IBM Tivoli Directory Server 6.2 is one of the supported LDAP servers for the OpenSSO server to provide authentication and authorization services. A specific sub configuration LDAPv3ForTivoli is available out of the box to support this server. You can find the data_store_tivoli.txt to create a new data store by supplying the -t LDAPv3ForTivoli option to the ssoadm tool. Here is the sample command that creates the datastore for Tivoli DS. The sample (data_store_tivoli. txt can be found as part of the code bundle) file contains the entries including the default group, that are shipped with the Tivoli DS for easy understanding. You can customize it to any valid values: ./ssoadm create-datastore -u amadmin -f /tmp/.passwd_of_amadmin "Tivoli-store" -t LDAPv3ForTivoli -D data_store_tivoli.txt

-e / -m

Data store for Active Directory

Microsoft Active Directory provides most of the LDAPv3 features including support for persistent search notifications. Creating a data store for this is also a straightforward process and is available out-of-the-box. You can find the data_ store_ad.txt to create a new data store by supplying the -t LDAPv3ForAD option to the ssoadm tool. Here is the sample command that creates the datastore for AD: ./ssoadm create-datastore -u amadmin -f /tmp/.passwd_of_amadmin "AD-store" -t LDAPv3ForAD -D data_store_ad.txt .

-e / -m

Data store for Active Directory Application Mode

Microsoft Active Directory Application Mode (ADAM) is the lightweight version of the Active directory with simplified schema. In the ADAM instance it is possible to set user password over LDAP unlike Active Directory where password-related operations must happen over LDAPS. Creating a data store for this is also a straightforward process and is available out-of-the-box. You can find the data_store_adam. txt to create a new data store by supplying the -t LDAPv3ForADAM option to the ssoadm tool: ./ssoadm create-datastore -u amadmin -f /tmp/.passwd_of_amadmin "ADAM-store" -t LDAPv3ForADAM -D data_store_adam.txt

[ 199 ]

-e / -m

Identity Stores

Datastore for OpenLDAP

OpenLDAP software is a free, open source implementation of the Lightweight Directory Access Protocol (LDAP) developed by the OpenLDAP project. It is released under its own BSD-style license called the OpenLDAP Public License. LDAP is a platform-independent protocol. Several common Linux distributions include OpenLDAP software for LDAP support. The software also runs on BSDvariants, as well as AIX, Android, HP-UX, Mac OS X, Solaris, Microsoft Windows (NT and derivatives, for example, 2000, XP, Vista, Windows 7, and so on), and z/OS. (http://en.wikipedia.org/wiki/OpenLDAP). Many commercial websites and organizations rely on the OpenLDAP server for their everyday operations. Adoption of OpenLDAP is steadily growing with strong developer community support. Even though OpenSSO does not provide out of the box Identity Repository plugin implementation for the OpenLDAP, it is relatively easy to integrate an existing OpenLDAP infrastructure with the OpenSSO Single Sign-On framework for authentication and authorization. For read-only operations such as authentication and authorization there is no schema extension required in the OpenLDAP server side. In this case certain functionalities (refer to the User schema section) of OpenSSO cannot be realized without extending the schema to include OpenSSO-specific object classes and attributes. In this section I am going to show you a few simple steps to configure the OpenLDAP that can be used as a user identity store for OpenSSO. Here are the sequence of steps: • • • • •

Configuring OpenLDAP suffix Extending schema Preparing the suffix with necessary entries Creating the OpenLDAP data store Testing the data store

Let us see how these steps can be accomplished in a less error-prone way.

Configuring an OpenLDAP suffix

There is a lot of information available on the Internet that describes how to install and configure the OpenLDAP server. In fact some of the Linux variants are automatically configured for OpenLDAP. We are going to create a suffix dc=opensso,dc=java,dc=net with an administrative user, cn=manager who will be the root user for this suffix. The following command performs the recently mentioned items: slapadd -d -1 < /tmp/init_suffix.ldif

[ 200 ]

Chapter 8

where /tmp/init_suffix.ldif contained: dn: dc=opensso,dc=java,dc=net objectClass: top objectClass: dcObject objectClass: organization o: opensso dc: opensso structuralObjectClass: organization dn: cn=manager,dc=opensso,dc=java,dc=net objectclass: inetuser objectclass: organizationalperson objectclass: person objectclass: top cn: manager sn: manager userPassword: secret12

This will create and initialize the suffix as shown in the LDIF we have just seen. Now you can issue: ldapsearch -x -h openldap.packt-services.net -D"cn=manager,dc=opensso,dc= java,dc=net" -w secret12 -b"dc=opensso,dc=java,dc=net" "cn=*"

to verify the suffix configuration. Once this is successful you can go ahead and extend the schema by following the instructions in the next section.

Extending the schema

You should be able to download or find the schema file along with the code bundle you got with this book. The schema file that contains the OpenSSO user schema for OpenLDAP is named as OpenSSO4OpenLDAP.schema. Copy this file to the OpenLDAP schema location, for example /etc/openldap/schema/. Then update the /etc/openldap/slapd.conf to include the schema after the default schema definitions. After updating the slapd.conf schema entries will look something like this: include include include include include

/etc/openldap/schema/core.schema /etc/openldap/schema/cosine.schema /etc/openldap/schema/inetorgperson.schema /etc/openldap/schema/nis.schema /etc/openldap/schema/OpenSSO4OpenLDAP.schema

After this update restart the server to realize the schema extensions. [ 201 ]

Identity Stores

Preparing the suffix with necessary entries

There are certain entries that might help you to streamline the data store creation process and subsequent identity CRUD operations from the administrative console of OpenSSO. These are not a must but are recommended. Execute the following command to add the entries: ldapmodify -x -h openldap -p 389 -D"cn=manager,dc=opensso,dc=java,dc=net" -w secret12 -c -a -f /tmp/template.ldif

Here is how the contents of the file /tmp/template.ldif looks: dn: ou=people,dc=opensso,dc=java,dc=net objectClass: top ou:people objectClass: organizationalUnit dn: ou=groups,dc=opensso,dc=java,dc=net ou:groups objectClass: top objectClass: organizationalUnit dn: cn=amadmin,ou=people,dc=opensso,dc=java,dc=net objectclass: inetuser objectclass: organizationalperson objectclass: person objectclass: top cn: amadmin sn: amadmin uid: amadmin userPassword: secret124 dn:cn=defaultGroup,ou=groups,dc=opensso,dc=java,dc=net objectclass: top objectclass: groupofnames member:cn=amadmin,ou=people,dc=opensso,dc=java,dc=net cn:default1

This completes the LDAP server preparation process. Now let us see how OpenSSO can be configured to talk to this server for storing identities.

[ 202 ]

Chapter 8

Creating an OpenLDAP data store

As I have mentioned earlier OpenSSO does not support an out of the box sub configuration in the Identity Repository service, we need to use the generic LDAPv3 sub configuration for OpenLDAP: ./ssoadm create-datastore -u amadmin -f /tmp/.passwd_of_amadmin -e / -m "OpenLDAP-store" -t LDAPv3 -D data_store_openldap.txt

This will create the data store in the OpenSSO configuration store. Note that there is no LDAPv3 configuration supported from the console, you need to always use the ssoadm tool to create the generic LDAPv3 configuration store. The file data_store_openldap.txt is available as part of the code bundle. You need to replace the openLDAP server name and port to match with your configuration.

Testing the data store

Once the data store is created successfully you can go ahead and log in to the OpenSSO console as the top level administrative user, then perform the user and group creation. User creation from the console will be seamless. However, the group creation will throw some exceptions, ignore them, they are harmless and there will be no functionality loss: ./ssoadm create-identity -i mytestgroup -t Group -u amadmin -f /tmp/. passwd_of_amadmin -e / Plug-in com.sun.identity.idm.plugins.ldapv3.LDAPv3Repo: Unable to find entry: cn=mytestgroup,ou=groups,dc=opensso,dc=java,dc=net

To verify the group has been created issue the following command: ./ssoadm list-identities -e / -t Group -u amadmin -f /tmp/.passwd_of_ amadmin -x "mytestgroup" mytestgroup (id=mytestgroup,ou=group,dc=opensso,dc=java,dc=net) Search of Identities of type Group in realm, / succeeded.

This completes the verification procedure along with the OpenLDAP schema extensions. There are some limitations that are known while using OpenLDAP as the user store. For instance there is no persistent search notification control (2.16.840.1.113730.3.4.3) implemented in OpenLDAP so you have to rely on the polling method to refresh the cache.

[ 203 ]

Download from Wow! eBook

Identity Stores

Multiple data stores

OpenSSO does support more than one data store to be configured for a given realm. In this scenario how can one fine-tune the specific privileges such as where to create users or groups. By default all the CRUD (create, read, update, and delete) operations will be applied to all of the available data stores unless the specific operations are disabled in the data store configuration page as shown in the following screenshot:

If you want to control specific operations on the selected data stores, then you might want to remove the operations from the supported types and operations as previously shown. If you want to disable all the group-related operations then just remove the group=read,create,edit,delete from the data store configuration or remove create if you do not wish to create groups in that data store. In case there are some exceptions that have occurred in one of the data stores you will not notice this because those exceptions will be masked if one of the data stores successfully performs the requested operations.

[ 204 ]

Chapter 8

Summary

In this chapter, we have seen how OpenSSO is designed to support the commercially available LDAP servers. There are certain Identity Repository plugins that enable the server to perform better without looking for any external input. We have discussed the caching and notification-related properties that form the key to achieving the optimal performance of the overall system. For consistent repeatability there is a property file for each type of supported LDAP server provided along with the code bundle. This would greatly ease the creation of the data stores. Finally we have dealt with the process of extending the OpenLDAP server schema to adapt it to work with OpenSSO as an identity store. The schema file is the core part of this process that needs to be properly added as given in the procedure. You can create more than one data store of the same type or varying types to meet the specific deployment architecture. One can fine-tune the permissions and type of entries that can be stored in an identity store. Identity services is becoming the buzz word in the industry. All the access and identity management product vendors are compelled to provide the identity web services feature. To that effect OpenSSO supports both SOAP and REST-based identity web services. In the next chapter we will be learning about the identity web services features provided by the OpenSSO server. Specifically the REST-based identity web services will be covered extensively.

[ 205 ]

RESTful Identity Services According to Wikipedia, Representational State Transfer (REST) is a style of software architecture for distributed hypermedia systems such as the World Wide Web. The term Representational State Transfer was introduced and defined by Roy Fielding in his doctoral dissertation. REST-style architectures consist of clients and servers. Clients initiate requests to servers; servers process requests and return appropriate responses. Requests and responses are built around the transfer of "representations" of "resources". A resource can be essentially any coherent and meaningful concept that may be addressed. A representation of a resource is typically a document that captures the current or intended state of a resource. At any particular time, a client can either be in transition between application states or "at rest". A client in a rest state is able to interact with its user, but creates no load and does not consume per-client storage on the set of servers or on the network. The client begins sending requests when they are ready to make the transition to a new state. While one or more requests are outstanding, the client is considered to be in transition. The representation of each application state contains links that may be used next time the client chooses to initiate a new state transition. REST was initially described in the context of HTTP. However, it is not limited to that protocol. RESTful architectures can be based on other Application Layer protocols if they already provide a rich and uniform vocabulary for applications based on the transfer of meaningful representational state. RESTful applications maximize the use of the pre-existing, well-defined interface and other built-in capabilities provided by the chosen network protocol, and minimize the addition of new application-specific features on top of it.

RESTful Identity Services

The recent rapid advancements and adoption of web services, Service-Oriented Architecture (SOA), and Representational State Transfer architectures within enterprises have left the industry wanting more. Organizations and developers, such as those who focus on Web 2.0, are demanding interface support from identity and access management software. In this chapter, let us focus on some of the RESTful features provided by the OpenSSO server, including the following: •

Authentication

•

Authorization

•

Session

•

Logging

•

Identity CRUD operations

You can obtain the list of web services end points provided by the OpenSSO server by entering the following URL: http://opensso.packt-services.net:9090/ opensso/identityservices. Assuming that you have set up the OpenSSO at this URL, for the sake of clarity, in the succeeding examples this URL will be quoted. Alternatively, to view the WSDL for the supported methods point your browser at http://opensso.packt-services.net:9090/opensso/identityservices/ IdentityServices?WSDL. In the next several sections you will be shown how the REST-based interfaces can be invoked for various supported methods. I will be using the curl utility for ease of use and brevity to make the point clear. Besides, the commands can simply be cut and pasted from the book onto your terminal to expedite your learning process. Remember the same thing can be achieved via a browser or other programs such as a PHP script. There are about 11 REST operations that are exposed in the OpenSSO server. These operations are supported out of the box configuration of OpenSSO; there are no special configurations required. The screenshot we are about to see illustrates those operations. You can find more detailed account on this subject in the article http://developers.sun.com/identity/reference/techart/id-svcs.html.

Prerequisites

The only prerequisite is to deploy and configure the OpenSSO web application on a supported container such as Apache Tomcat. For this exercise, I have deployed the server on Apache Tomcat 6.0.20 and leveraged the embedded identity data store to perform these simple operations. If you would like to work on the role IDtype, then you must use a supported identity data store such as the Oracle Directory Server Enterprise Edition. [ 208 ]

Chapter 9

Another key thing here, as mentioned earlier, is that I would like to use the curl utility. It supports both GET/POST methods, and so easily shows the input and output parameters, to verify these REST operations.

[ 209 ]

RESTful Identity Services

Invoking REST interfaces

The arguments continue on whether REST is a newer standard or yet another form of RPCs. There is a lot of literature available on the Web to learn more about the RESTful architectures and their design. It is beyond the scope of this book to discuss those architectural aspects of REST. Let us learn how one can invoke the REST interfaces of the OpenSSO server. The beauty of RESTful interfaces is their flexibility and adaptability for a wide range of purposes. These interfaces can be invoked either through a browser or from a high-level language program; it just opens up an HTTP URL connection to the server.

Authentication

All the REST interfaces require a valid SSO token in order to access them except the authentication. It takes a username and a password parameter to issue a valid SSO token provided the credentials are valid. There are multiple ways to invoke this authentication interface. Typically this interface will be invoked to obtain an SSO token in order to access a resource that is protected by OpenSSO. Let us see some examples on invoking the authenticate interface: curl -v -d "username=thanga&password=secret" http://opensso.packtservices.net:9090/opensso/identity/authenticate * About to connect() to opensso.packt-services.net port 9090 * Trying 192.168.1.120... * connected * Connected to opensso.packt-services.net (192.168.1.120) port 9090 > POST /opensso/identity/authenticate HTTP/1.1 User-Agent: curl/7.12.1 (i386-redhat-linux-gnu) libcurl/7.12.1 OpenSSL/0.9.7a zlib/1.2.1.2 libidn/0.5.6 Host: opensso.packt-services.net:9090 Pragma: no-cache Accept: */* Content-Length: 32 Content-Type: application/x-www-form-urlencoded &username=thanga&password=secret< HTTP/1.1 200 OK < Server: Apache-Coyote/1.1 < Content-Type: text/plain;charset=UTF-8 < Content-Length: 72 < Date: Sun, 27 Jun 2010 16:27:24 GMT token.id=AQIC5wM2LY4SfcxRFMGPbmwEtT9nCukQJSfbnG6lTmIt978.*AAJTSQACMDE.* * Connection #0 to host opensso.packt-services.net left intact * Closing connection #0

[ 210 ]

Chapter 9

As you can see, we are trying to authenticate to the server as thanga with credential secret. We have forced the POST method using the -d option to the curl command. This, in turn, produced an access log at the Apache Tomcat server, which looks something like this: 192.168.1.120 - - [27/Jun/2010:09:27:24 -0700] "POST /opensso/ identity/authenticate HTTP/1.1" 200 72

So far, so good. No issues. We got the SSO token with the session identifier (returned as token.id). Well, let us use the browser to perform the same authentication operation. Enter http://opensso.packt-services.net:9090/opensso/ identity/authenticate?username=thanga&password=secret.

Now let us look at the access log of the container to observe what kind operation is logged: 192.168.1.120 - - [27/Jun/2010:09:40:30 -0700] "GET /opensso/identity/ authenticate?username=thanga&password=secret HTTP/1.1" 200 72

Here the browser initiated a HTTP GET operation to obtain the token and the username and password which are logged in plain text in the container's access log file. This is considered a huge security concern and this problem has been addressed in the OpenSSO 8.0 Update 2 commercial version of the product. With that fix, no matter how you invoke, the authenticate interface will only support the POST method. However, this fix is not available in the Express 9 candidate that has been used to generate examples for this book.

Authenticating with URL parameters

Alternatively, the REST authentication interface can be accessed with some of the URL parameters (not all) that we discussed in Chapter 4. The following example shows you how to authenticate to a specific realm with module-based authentication: curl -d "username=thanga&password=secret&module=ldap&realm=/red" http:// opensso.packt-services.net:9090/opensso/identity/authenticate token.id=AQIC5wM2LY4SfczR0j8j-_4BBvU2QijcYyiU72wX5F4d3Ew.*AAJTSQACMDE.*

[ 211 ]

RESTful Identity Services

In this scenario, the user has been authenticated to the sub realm /red using the LDAP authentication module instance named ldap. You should be cautious about using the parameters, though by design it is expected to work. However, the express build 9 exhibits some buggy behavior in the internal authentication as it does not set a proper realm and module instance in the SSO token.

Validating an SSO token

I am sure you are now familiar with obtaining an SSO token using the authenticate interface. Now let us see how a pre-existing token can be validated using the REST interface. It is very critical for the protected application to validate that the token sent by the client is still valid and has not expired or timed out. This can be easily accomplished by invoking the Boolean method isTokenValid that would return true if the given SSO token is valid. To invoke the isTokenValid method, you should first have a valid token which can be obtained by using the authenticate method: curl -d "&username=thanga&password=secret" http://opensso.packt-services. net:9090/opensso/identity/authenticate token.id=AQIC5wM2LY4SfcyozDeLktwuC73qWK1sggRgYM0jFIUjLhA.*AAJTSQACMDE.* curl -d "tokenid=AQIC5wM2LY4SfcyozDeLktwuC73qWK1sggRgYM0jFIUjLhA.*AAJTSQACMDE.*" http://opensso.packt-services.net:9090/opensso/identity/isTokenValid boolean=true

After getting the token, you can apply the isTokenValid method to validate the session token. It will return boolean=true if valid, otherwise boolean=false. There is also another way to supply the tokenid—by using the cookie name. An example of an out of the box cookie name is iPlanetDirectoryPro, so you can supply the cookie name using the -b option to the curl command, as follows: curl -b "iPlanetDirectoryPro=AQIC5wM2LY4SfcyozDeLktwuC73qWK1sggRgYM0jF IUjLhA.*AAJTSQACMDE.*" http://opensso.packt-services.net:9090/opensso/ identity/isTokenValid boolean=true

This is a GET operation as opposed to POST.

[ 212 ]

Chapter 9

Invalidating session (logout)

Like the browser there is an interface provided in the REST to invalidate or logout the session. OpenSSO provides the logout interface to destroy a valid session, a generic invalid session. A GeneralFailure Service URL not found exception will be returned upon invoking this method with an invalid session: curl -d "&username=thanga&password=secret&module=ldap&realm=/red" http:// opensso.packt-services.net:9090/opensso/identity/authenticate token.id=AQIC5wM2LY4SfcyteboiZeMaSJaKP8DFLWxEtecVHXwmPdA.*AAJTSQACMDE.* curl -d "subjectid=AQIC5wM2LY4SfcyteboiZeMaSJaKP8DFLWxEtecVHXwmPdA. *AAJTSQACMDE.*" http://opensso.packt-services.net:9090/opensso/identity/ logout

The first command is used to get the token for the user identity thanga. Subsequently, it will be destroyed by invoking the logout method with subjectid containing the session handle. The same thing can be achieved by using a GET operation along with the iPlanetDirectoryPro cookie value: curl -b "iPlanetDirectoryPro=AQIC5wM2LY4SfcyteboiZeMaSJaKP8DFLWxEtec VHXwmPdA.*AAJTSQACMDE.*" http://opensso.packt-services.net:9090/opensso/ identity/logout

Creating log events

Logging security events is one of the core competencies for the access management products such as OpenSSO. It is possible to create the log events or any loggingrelated message by invoking the log REST method. Essentially it takes three mandatory parameters in order to perform a server-side logging: •

appid: It is the authorization token that has the permission to write to log files. This could be the token of logadmin or amadmin.

•

subjectid: It is the identity subject whose logging event is being written to the log store.

•

logname: It implies the database table or the flat file name that will be created if not existing already. It could be any one of the existing log module names as well, such as amConsole.access.

•

message: It is the actual event name or text that will be written into the log file or DB table.

curl -d "appid=AQIC5wM2LY4Sfcxuwn4vnLgPg20M9RXroNx2zaFdCf91gac.*AAJTSQAC MDE.*&subjectid=AQIC5wM2LY4SfczSeGfek2Tgl8M6dtwgmg4xjSzswKmpNeY.*AAJTSQ ACMDE. *&logname=CURLdb&message=testmessagefromthecurl" http://opensso. packt-services. net:9090/opensso/identity/log [ 213 ]

RESTful Identity Services

As you can see, there are two different SSO tokens supplied. One, the identity whose events are being logged using the privileged token provided in the appid parameter. The other token provided in the subjectid parameter, this will be user to whom the log events are written. The resulting content of the log file (CURLdb) will appear as follows: #Version: 1.0 #Fields: time Data Domain LoggedBy

LoginID ContextID IPAddr MessageID ModuleName

LogLevel NameID HostName

"2010-06-27 11:50:02" /export/ssouser/TOMCAT/opensso-9090/opensso/ log/ "cn=dsameuser,ou=DSAME Users,dc=opensso,dc=java,dc=net" 4b3c1b92dbed22c501 "Not Available" INFO dc=opensso,dc=java,dc=net "cn=dsameuser,ou=DSAME Users,dc=opensso,dc=java,dc=net" LOG-1 CURLdb "Not Available" 192.168.1.120 "2010-06-27 11:50:02" testmessagefromthecurl id=thanga,ou=user,dc=o pensso,dc=java,dc=net 4b7c4ee68a30a02b01 "Not Available" INFO dc=opensso,dc=java,dc=net id=amadmin,ou=user,dc=opensso,dc=java,dc= net "Not Available" CURLdb "Not Available" 192.168.1.120

Authorization

Authorization is one of the most frequently invoked interfaces in the access management security arena. OpenSSO does provide a Boolean method that would yield true or false for a given resource URI. To test this interface, apparently you must set up a policy for the URI used in the authorize method. It takes three mandatory parameters: •

action: Policy action whether a GET or POST

•

uri: A resource for which the authorization decision is requested

•

subjectid: SSO token of the authenticated identity who is trying to access the resource URI

Assuming the policies are set up (refer to Chapter 6) appropriately, here is the sample command to invoke the authorize method: curl -d "uri=http://payslip.packt-services.net:7070/index.html&subjectid= AQIC5wM2LY4SfczSeGfek2Tgl8M6dtwgmg4xjSzswKmpNeY.*AAJTSQACMDE.*&action=PO ST" http://opensso.packt-services.net:9090/opensso/identity/authorize boolean=false curl -d "uri=http://payslip.packt-services.net:7070/index.html&subjectid =AQIC5wM2LY4SfczSeGfek2Tgl8M6dtwgmg4xjSzswKmpNeY.*AAJTSQACMDE.*&action=G ET" http://opensso.packt-services.net:9090/opensso/identity/authorize boolean=true

[ 214 ]

Chapter 9

The policy rules for the resource URI used will resemble the following screenshot:

Identity CRUD operations

Unlike other Access Management products, OpenSSO provides extensive identity operations interfaces for provision and management of those identities. In the REST interfaces arena, there are a slew of methods exposed to perform identity CRUD (create, read, update, and delete) operations. In this section, let us explore some of those methods with specific examples.

Searching identities

The search REST interface will query the configured datastores for identities matching the search filter supplied, using the filter parameter. There are other parameters that are mandatory for this interface. They are as follows: •

filter: Defines a set of criteria that controls what is returned by

•

attributes_names: Defines one or more identity attributes for which the search is to be performed

•

attributes_values_{values_of-attributes_names}: Defines the value of the attribute (defined by attributes_names) that is being searched

•

admin: Defines the SSO tokenID of the user with the necessary privileges to search the identity objects; for example, amadmin

the operation

[ 215 ]

Download from Wow! eBook

RESTful Identity Services

Searching for user identities

To search for the users you need to supply the objecttype=user: curl -d"&filter=*&attributes_names=objecttype&attributes_values_objectty pe=user&admin=AQIC5wM2LY4SfcyzMMSQfpvjKfTC1vchgxDh5qFqe1IyWc8.*AAJTSQACM DE.*" http://opensso.packt-services.net:9090/opensso/identity/search

For example: string=bob string=anonymous string=andy string=frank string=dave string=newauduin string=thanga string=amAdmin string=chris string=openldap

Searching groups

To list out all the groups in the system, just follow the following command line. However, if you wanted to list roles (which is only supported on the Oracle Directory Server Enterprise Edition) use role in place of group in the search method: curl -d"&filter=*&attributes_names=objecttype&attributes_values_objectty pe=group&admin=AQIC5wM2LY4SfcyzMMSQfpvjKfTC1vchgxDh5qFqe1IyWc8.*AAJTSQACM DE.*" http://opensso.packt-services.net:9090/opensso/identity/search

For example: string=manager string=customer string=employee string=everyone

Searching for agents

You can use the following command to list all the agents in the server: curl -d"&filter=*&attributes_names=objecttype&attributes_values_objectty pe=agent&admin=AQIC5wM2LY4SfcyzMMSQfpvjKfTC1vchgxDh5qFqe1IyWc8.*AAJTSQACM DE.*" http://opensso.packt-services.net:9090/opensso/identity/search

[ 216 ]

Chapter 9

For example: string=SecurityTokenService string=payslip string=agentAuth string=wsp string=wsc

Again, all of these operations are performed over HTTP POST.

Retrieving identity attributes

All of the above commands helped us search and return all the identities matching specific search criteria. What if we wanted to query all or a specific attribute of an authenticated identity? How do we achieve that? Yes, there is a way to get this working in OpenSSO using the REST interface. The attributes REST interface provides the attribute query feature: curl -d"attributes_names=*&subjectid=AQIC5wM2LY4Sfcy3-h9A1_Tle0YTRqor9wzra_KwJRfYYA.*AAJTSQACMDE.*" http://opensso.packt-services. net:9090/opensso/identity/attributes

Here are a few illustrations: userdetails.token.id=AQIC5wM2LY4Sfcy3-h9A1_Tle0Y-TRqor9wzra_ KwJRfYYA.*AAJTSQACMDE.* userdetails.attribute.name=sunIdentityMSISDNNumber userdetails.attribute.name=mail userdetails.attribute.name=sn userdetails.attribute.value=amAdmin userdetails.attribute.name=givenName userdetails.attribute.value=amAdmin userdetails.attribute.name=telephoneNumber userdetails.attribute.name=employeeNumber userdetails.attribute.name=postalAddress userdetails.attribute.name=iplanet-am-user-success-url userdetails.attribute.name=cn userdetails.attribute.value=amAdmin userdetails.attribute.name=roles userdetails.attribute.value=Top-level Admin Role userdetails.attribute.name=iplanet-am-user-failure-url userdetails.attribute.name=inetUserStatus userdetails.attribute.value=Active userdetails.attribute.name=dn userdetails.attribute.value=uid=amAdmin,ou=people,dc=opensso,dc=java, dc=net userdetails.attribute.name=iplanet-am-user-alias-list

[ 217 ]

RESTful Identity Services

This will get all the user attributes of an authenticated user whose SSO token is provided in the subjectid parameter. In case you are looking for a specific attribute for the user, then you should be leveraging the read interface instead of attributes. The read method requires you to supply the administrative user token or any privileged user token (someone who has search privileges to the user identities). In the following example we see how the inetuserstatus attribute value can be obtained for the user thanga by supplying the top level administrative user token: curl -d"name=thanga&attributes_names=inetuserstatus&admin=AQIC5wM2LY4Sf cydrf7j_P55uDmbs3lPSlKKaDgWelBI4oQ.*AAJTSQACMDE.*" http://opensso.packtservices.net:9090/opensso/identity/read

Here are a few examples: identitydetails.name=thanga identitydetails.type=user identitydetails.realm=dc=opensso,dc=java,dc=net identitydetails.attribute= identitydetails.attribute.name=inetuserstatus identitydetails.attribute.value=Active

In the same way, you can get any other identity attributes.

Creating agent identities

Creating identities is a straightforward process as it does not involve too many parameters. Let us start with the agent type. The following sequence of commands will create a web agent profile named webagent70, followed by a search for this profile to verify its creation: curl -d "identity_name=webagent70&identity_attribute_ names=userpassword&identity_attribute_values_ userpassword=secret123&identity_realm=/&identity_type=Agent&admin=AQIC5w M2LY4SfcyAE_hl9mLbroCALqxF6duZrCGSEBNokLk.*AAJTSQACMDE.*" http://opensso. packt-services.net:9090/opensso/identity/create

This command will return nothing if the process is successful, otherwise you will be noticing the exception as documented in the WSDL. To make sure the profile has been created successfully, let us search for the agent with the name webagent70: curl -d "&filter=webagent70&attributes_names=objecttype&attributes_ values_objecttype=agent&admin=AQIC5wM2LY4SfcyAE_hl9mLbroCALqxF6duZrCGSE BNokLk.*AAJTSQACMDE.*" http://opensso.packt-services.net:9090/opensso/ identity/search string=webagent70 [ 218 ]

Chapter 9

Creating user identities

Creating users from the REST interface method create is relatively more involved than creating an agent. All the attributes associated with their values need to be properly formatted before sending it to the REST call. Let us see this process with a simple example that shows you how to create the user with minimum required attributes: curl -d"identity_name=rest_user_created&identity_ attribute_names=userpassword&identity_attribute_values_ userpassword=secret12&identity_attribute_names=sn&identity_attribute_ values_sn=sn_for_rest_user&identity_attribute_names=cn&identity_ attribute_values_cn=cn_of_REST_user&identity_realm=/&identity_type=use r&admin=AQIC5wM2LY4SfcyAE_hl9mLbroCALqxF6duZrCGSEBNokLk.*AAJTSQACMDE.*" http://opensso.packt-services.net:9090/opensso/identity/create

If you have not noticed any errors after executing this command, then it is most likely that the user creation is successful. Now try the next command to verify whether the identity exists. If it does not exist, you will see the object not found exception. A user with name rest_user_created will be added to the system: curl -d "&filter=rest_user_created&attributes_ names=objectclass&attributes_values_objectclass=person&admin=AQIC5wM2LY 4SfcyAE_hl9mLbroCALqxF6duZrCGSEBNokLk.*AAJTSQACMDE.*" http://opensso. packt-services.net:9090/opensso/identity/searchstring=rest_user_created

All these curl commands should appear in one line, for readability some may appear in multiple lines.

Creating group identities

Just like users, groups can be created by changing the identity_type=group. Unlike the user identities, the group requires only its name as the required attribute: curl -d "identity_name=rest_group&identity_realm=/&identity_type=group &admin=AQIC5wM2LY4Sfcw048RQCRtKfR_N1k-eSmONGbH9RR5VAZU.*AAJTSQACMDE.*" http://opensso.packt-services.net:9090/opensso/identity/create

In order to verify, just execute the following command to view the group you have just created: curl -d "&filter=rest_group&attributes_names=objecttype&attributes_ values_objecttype=group&admin=AQIC5wM2LY4Sfcw048RQCRtKfR_N1k-eSmONGbH9R R5VAZU.*AAJTSQACMDE.*" http://opensso.packt-services.net:9090/opensso/ identity/search string=rest_group [ 219 ]

RESTful Identity Services

Updating identities

One of the key operations in the CRUD series is that of updating. As you might have guessed, the REST interface for performing this action is expressed as the update method. Clients can call this method using a privileged session token to update the identity attributes. Here is an example of how to update the mail attribute of the user we have created in the previous section, Creating user identities: curl -d "attributes_names=mail&name=rest_user_created&admin=AQIC5wM2LY4Sf cwEzYdcBxZDvBximnLuk4-wp9J1ZB2VrDM.*AAJTSQACMDE.*" http://opensso.packtservices.net:9090/opensso/identity/read identitydetails.name=rest_user_created identitydetails.type=user identitydetails.realm=dc=opensso,dc=java,dc=net identitydetails.attribute= identitydetails.attribute.name=mail

There is no mail attribute value set for this user. Now let's use the update interface to set a valid e-mail address value to this user: curl -d "identity_name=rest_user_created&identity_attribute_ names=mail&identity_attribute_values_mail=indira.thangasamy@ pack-services.net&admin=AQIC5wM2LY4SfcwEzYdcBxZDvBximnLuk4wp9J1ZB2VrDM.*AAJTSQACMDE.*" http://opensso.packt-services.net:9090/ opensso/identity/update

This command will update the mail attribute of the user supplied. Let us verify whether the new value indeed gets stored in the backend store: curl -d "attributes_names=mail&name=rest_user_created&admin=AQIC5wM2LY4Sf cwEzYdcBxZDvBximnLuk4-wp9J1ZB2VrDM.*AAJTSQACMDE.*" http://opensso.packtservices.net:9090/opensso/identity/read identitydetails.name=rest_user_created identitydetails.type=user identitydetails.realm=dc=opensso,dc=java,dc=net identitydetails.attribute= identitydetails.attribute.name=mail identitydetails.attribute.value=indira.thangasamy@pack-services.net

You will notice that the new value for the mail attribute has been stored in the data store. In this manner you should be able to update any of the supported identity attributes.

[ 220 ]

Chapter 9

Deleting identities

So far we have covered the rest of the CRUD operations except the delete operation. It is the last one in the life cycle of an identity anyway. Now let us cover the delete REST method provided by the OpenSSO to delete the supported identities. Let us start with deleting the user identities.

Deleting user identities

The REST interface does not support deletion of multiple user identities. You have to invoke the delete method each time you want to delete the identity. To delete the user, you should make sure the user exists in the system before trying to delete, otherwise an object not found exception will be thrown: curl -d "identity_name=rest_user_created&identity_type=user&admin=AQIC5wM 2LY4SfcwufmBz118UhSXp5613iygUtCQK95-I6Lk.*AAJTSQACMDE.*" http://opensso. packt-services.net:9090/opensso/identity/delete

The admin token should have proper privileges to delete the user identities from the system, otherwise a privilege exception will be printed. This command will remove the user name rest_user_created from the underlying data stores.

Deleting group identities

Just like the user identities, the group identities can be removed from the system by following a syntax that is similar to the following command: curl -d "identity_name=rest_group&identity_type=group&admin=AQIC5wM2LY4Sf cwufmBz118UhSXp5613iygUtCQK95-I6Lk.*AAJTSQACMDE.*" http://opensso.packtservices.net:9090/opensso/identity/delete

Obviously this will remove the group rest_group from the server.

Deleting the agent identities

Let us conclude the CRUD operations by showing you how to remove an agent identity from the server. Let us delete the webagent70 profile that we have created in the beginning of this section: curl -d "identity_name=webagent70&identity_type=agent&admin=AQIC5wM2LY4Sf cwufmBz118UhSXp5613iygUtCQK95-I6Lk.*AAJTSQACMDE.*" http://opensso.packtservices.net:9090/opensso/identity/delete

After running this command successfully the web agent profile webagent70 will be permanently removed from the OpenSSO server. All the create, update, and delete methods are returning void so there will be no messages printed after a successful execution. [ 221 ]

RESTful Identity Services

Other REST interfaces

There are some REST interfaces available in OpenSSO, but those interfaces are not public to the end user. These interfaces are used internally by the clients such as Policy agents. It includes the agent profile and the profile attributes of the authenticated identity, when attribute fetch is enabled. Here is one such interface used by the policy agents to retrieve the agent profile with the name payslip: curl -d "name=payslip&attributes_names=realm&attributes_values_ realm=%2F&attributes_names=objecttype&attributes_values_objecttype=Agen t&admin=AQIC5wM2LY4SfcyVaDWqdD10Rs2dbFYenGKLy9EMznkLSfE.*AAJTSQACMDE.*" http://opensso.packt-services.net:9090/opensso/identity/xml/read

This concludes the list of all the supported REST interfaces that are supported by the OpenSSO server. For more detailed information, please visit the OpenSSO wiki by pointing your browser to http://wikis.sun.com/display/OpenSSO/ OpenSSO+Resource+Center.

Summary

In this chapter we have extensively covered most of the supported REST interfaces of OpenSSO identity web services. It does have decent support for the operations that are typically consumed by the client-side programs. Nevertheless, as you might have noticed, none of the administrative or monitoring interfaces are exposed through the REST interfaces intentionally. This makes sense as the administrative activities can be carried out using the console. Any operation that is performed on identities via the REST interfaces will be reflected on all of the configured data stores in the realm. When these interfaces are invoked using a client browser, the customer must make sure that the values are encoded appropriately. There is a nice blog entry on OpenAM REST operations at http://blogs.forgerock.org/ petermajor/2010/05/using-the-rest-api-for-identity-management/. It includes some tips and some other comprehensive help as well. So far we have discussed most of the core services provided by the OpenSSO, but you might be wondering, "What if my server crashed? What if my configuration is corrupted or lost? How do I recover from the crash?" next chapter is the answer to your questions. In the succeeding chapter we are to going focus on backup and recovery process at length. Another interesting topic that is waiting to be discovered by you is the auditing feature. Auditing forms the third A in the AAA (Authentication, Authorization, and Audit) which is a critical piece in access management. In the next chapter, you can find various auditing features and ways to configure them in OpenSSO.

[ 222 ]

Backup, Recovery, and Logging Backup and recovery is one of the most important aspects of any enterprise product deployment and administration. If a server crashed and there was no way to recover it, the devastating results to a business could include lost data, lost revenue, and customer dissatisfaction. Whether companies deploy a single server or multiple servers in the cluster, they share one common factor—the need to back up important configuration data and protect themselves from disaster by developing a backup and recovery plan. A backup is a representative copy of data. This copy can include important parts of a server configuration, such as the core service configuration data, schema files, and LDAP indices. A backup can protect from unexpected data loss caused by an application misconfiguration or some other environmental factors, by providing a way to restore original data. The phrase "backup and recovery" usually refers to the transfer of copied files from one location to another, along with the various operations performed on these files. OpenSSO provides utilities that can be invoked with proper procedure to backup the server configuration data. When a crash or data corruption occurs, the server administrator must initiate a recovery operation. Recovering a backup involves the following two distinct operations: •

Restoring the configuration files

•

Restoring the XML configuration data that was backed up earlier

In general, recovery refers to the various operations involved in restoring, rolling forward, and rolling back a backup. Backup and recovery refers to the various strategies and operations involved in protecting the configuration database against data loss, and reconstructing the database should a loss occur.

Backup, Recovery, and Logging

In this chapter, you should be able to learn about how to use the tools provided by OpenSSO to perform the following: •

OpenSSO configuration backup and recovery

•

Test to production

•

Trace and debug level logging for troubleshooting

•

Audit log configuration using flat file

•

Audit log configuration using RDBMS

•

Securing the audit logs from intrusion

OpenSSO deals with only backing up the configuration data of the server as the identity such as users, groups, and roles data backup and recovery will be handled by the enterprise level identity management suite of products.

Backing up configuration data

I am sure you are familiar now with the different configuration stores supported by the OpenSSO, an embedded store (based on OpenDS), and a highly scalable Directory Server Enterprise Edition. Regardless of the underlying configuration type, there are certain files that are created in the local file system on the host where the server is deployed. These files (such as bootstrap file) contain critical pieces of information that helps the application to initialize, any corruption in these files could cause the server application not to start. Hence it becomes necessary to backup the configuration data stored in the file system. As a result, we could term the backup and recovery as a two step process: •

Backup the configuration files in the local file system

•

Backup the OpenSSO configuration data in the LDAP configuration

Let us briefly discuss what each option means and when to apply them.

[ 224 ]

Chapter 10

Backing up the OpenSSO configuration files

Typically the server can fail to come up for two reasons. Either because it could not find the right configuration file that will locate the configuration data store or because the data contained in the configuration store is corrupted. It is the simplest case I took up for this discussion because there could be umpteen reasons that could cause a server to fail to start up. OpenSSO provides a subcommand export-svccfg as part of the ssoadm command line interface. Using this the customer can only backup the configuration data that is stored in the configuration store, provided the configuration store is up and running. This backup will not help if the disk that holds the configuration files such as the bootstrap and OpenDS schema files crashed, because the backup obtained using the export-svc-cfg will not contain these schema and bootstrap files. This jeopardizes the backup and recovery process for the OpenSSO. This is why backing up the configuration directory becomes inevitable and vital for the recovery process. To backup the OpenSSO configuration directory, you can just use any file archive tool of your choice. To perform this backup, log on to the OpenSSO host as the OpenSSO configuration user, and execute the following command: zip -r /tmp/opensso_config.zip /export/ssouser/opensso1/

This will backup all the contents of the configuration directory (in this case /export/ ssouser/opensso1). Though this will be the recommended way to backup, there

may be server audit and debug logs that could fill up the disk space as you perform a periodic backup of this directory. The critical files and directories that need to be backed up are as follows: •

bootstrap

• • •

opends (whole directory if present)

•

certificate stores

.version .configParam

The rest of the content of this directory can be restored from your staging area. If you have customized any of the service schema under the /config/ xml directory, then make sure you back them up.

[ 225 ]

Backup, Recovery, and Logging

This backup is in itself enough to bring up the corrupted OpenSSO server. When you backup the opends directory all the OpenSSO configuration information will also get backed up, so you really do not need to have the backup file that you would generate using the export-svc-cfg. This kind of backup will be extremely useful and is the only way to perform the crash recovery. If the OpenDS is itself corrupted due to its internal database or index corruption, it will not start. Hence one cannot access the OpenSSO server or ssoadm command line tool to restore the XML backup. So, it is a must to backup your configuration directory from the file system periodically.

Backing up the OpenSSO configuration data

The process of backing up the OpenSSO service configuration data is slightly different from the complete backup of the overall system deployment. When the subcommand export-svc-cfg is invoked, the underlying code exports all the nodes under the ou=services,ROOT_SUFFIX of the configuration directory server: ./ssoadm export-svc-cfg -u amadmin -f /tmp/passwd_of_amadmin -e secretkeytoencryptpassword -o /tmp/svc-config-bkup.xml

To perform this, you need to have the ssoadm command line tool configured. The options supplied to this command are self-explanatory except maybe the -e . This takes a random string that will be used as the encryption secret to encrypt the password entries in the service configuration data. For example, the RADIUS server's share secret value. You need this key to restore the data back to the server. The OpenSSO and its configuration directory server must be running in good condition in order to be successful with this export operation. This backup will be useful in the following cases: •

Administrator accidently deleted some of the authentication configurations

•

Administrator accidently changed some of the configuration properties

•

Somehow the agent profiles have lost their configuration data

•

Want to reset to factory defaults

In any case, one should be able to authenticate to OpenSSO as an admin to restore the configuration data. If the server is not in that state, then crash recovery is the only option. In the embedded store configuration case this means unzipping the file system configuration backup obtained as described in the Backing up the OpenSSO configuration files section.

[ 226 ]

Chapter 10

For the configuration data that is stored in the Directory Server Enterprise Edition, the customer should use the tools that are bundled with the Oracle Directory Server Enterprise Edition to backup and restore.

Crash recovery and restore

In the previous section, we briefly covered the crash recovery part of it. When a crash occurs in the embedded or remote configuration store, the server will not come up again unless it is restored back to a valid state. This may involve restoring the proper database state and indexes using a known valid state backup. This backup may have been obtained by using the ODSEE backup tools or simply zipping up the configuration file system of OpenSSO, as described in the Backing up the OpenSSO configuration files section. You need to bring back the OpenSSO server to a state where the administrator can log in to access the console. At this point the configuration exported to XML, as described in the Backing up the OpenSSO configuration data section can be used. Here is a sample execution of the import-svccfg subcommand. It is recommended to backup your vanilla configuration data from the file system periodically to use it in the crash recovery case (where the embedded store itself is corrupted). Backup of configuration data using the export-svc-cfg should be done frequently: ./ssoadm import-svc-cfg -u amadmin -f /tmp/passwd_of_amadmin -e mysecretenckey -X /tmp/svc-config-bkup.xml

This will throw an error (because we have intentionally provided a wrong key) claiming that the secret key provided was wrong (actually it will show a string such as the following, that is a known bug): import-service-configuration-secret-key

This is the key name that is supposed to contain a corresponding localizable error string. If you provide the correct encryption key, then it will import successfully: ./ssoadm import-svc-cfg -u amadmin -f /tmp/passwd_of_amadmin -e secretkeytoencryptpassword -X /tmp/svc-config-bkup.xml Directory Service contains existing data. Do you want to delete it? [y|N] y Please wait while we import the service configuration... Service Configuration was imported.

[ 227 ]

Download from Wow! eBook

Backup, Recovery, and Logging

Note that it prompts before overwriting the existing data to make sure that the current configuration is not overwritten accidently. There is no incremental restore so be cautious while performing this operation. An import with a wrong version of the restore file could damage a working configuration. It is always recommended to backup the existing configuration before importing an existing configuration backup file. If you do not want to import the current file just enter N and the command will terminate without harming your data. Well, what happens if customers do not have the configuration files backed up? Suppose customers do not have the copy of the configuration files to restore, they can reconfigure the OpenSSO web application by accessing the configurator (after cleaning up existing configuration). Once they configure the server, they should be able to restore the XML backup. Nevertheless, the new configuration must match all the configuration parameters that were provided earlier including the hostname and port details. This information can be found in the .configParam file. If you are planning to export the configuration to a different server than the original server, then you should be referring to the Test to production section, that covers the details on how customers can migrate the test configuration to a production server. It requires more steps than simply restoring the configuration data.

Test to production

Every customer who deploys a software product knows the importance of testing their software in a pre-production environment, because there's always that slight chance that something may be different from the development environment. This is why typically the companies who develop and deploy enterprise software have a development environment, a staging environment, and a production environment. The development environment, as you might expect, is where things are developed and unit tested. However, staging is where things become different. This is where your environment should replicate, as closely as possible, your production environment. Although it's not always entirely possible to completely reproduce it, the closer, the better. Production is your live environment.

[ 228 ]

Chapter 10

Once they test out the product in a pre-production (staging) environment, they would like to move this configuration to the production environment. In the production environment only the physical host names, IP addresses, and domain name systems will be different. The rest of the OpenSSO configuration parameters such as the policy, authentication, and identity store configurations would be likely to be the same. Customers should be able to export the configuration in the staging area and import it into a production environment by just replacing the host and IP address-specific information. By the way OpenSSO does not store any IP addresses on the server in the configuration store or flat file. This process is called migrating or converting from test to production. OpenSSO can be deployed in a staging environment and after proper validations its configuration can be imported to a production server with minimal efforts.

Performing the configuration change

To move the OpenSSO configuration from test configuration to production environment, or if you simply need to change the deployment URI, server hostname, or the configuration root suffix all you need to do is to execute the following simple steps: •

Export the configuration data from the test server

•

Configure the OpenSSO on the production server

•

Import the tested configuration data after adapting it to the production system

Configuring the export test server

For this exercise let us consider two OpenSSO systems, one deployed in the test environment and the other deployed on the production system. As we discussed earlier, the test server is meant to validate the configurations before deploying it to a production system. Once the customer validates the use cases and perhaps the performance of the server, they will roll out into the production. Typically the production systems would be in a separate network and likely in a different domain. As it has already been tested in a different host, all the customers need to do is to replace the host name in the configuration and load the configuration into the production system, then everything should work without any service interruption or extensive configuration changes. Well, how would one perform this? Let us consider the two servers with corresponding deployment data given in the following table: Deployment Data

Test Server

Production Server

amadmin password

tEstSecre1

tEstSecre1

Amldapuser password

TesTAgen1

TesTAgen1 [ 229 ]

Backup, Recovery, and Logging

Deployment Data

Test Server

Production Server

Deployment URI

/olduri

/newuri

Server Name

oldhost.packt-services.net

newhost.new-services.com

Server Port

8080

9090

Configuration Directory Location

/export/ssouser/configolduri

/export/ssouser/confignewuri

Bootstrap File Path

/export/ssouser/. openssocfg/AMConfig_ export_ssouser_tomcat-8080_ apache-tomcat-6.0.20_ webapps_olduri_

/export/ssouser/. openssocfg/AMConfig_ export_ssouser_tomcat-9090_ apache-tomcat-6.0.20_ webapps_newuri_

Configuration Root Suffix

o=oldsuffix.com

o=newsuffix.com

Cookie Domain

.packt-services.net

.new-services.com

Encryption Key (am. encryption.pwd)

OpenSSOEncryptionKey

OpenSSOEncryptionKey

Log on to the test server oldhost.packt-services.net as the OpenSSO runtime user (in this case ssouser) assuming the ssoadm tool is already configured. Invoke the following command to export the configuration of the test server: ./ssoadm export-svc-cfg -e thisisthesecretkey -u amadmin -f /tmp/passwd_ of_amadmin -o /tmp/TestServerConfig.xml

This will export the test server's configuration data into an XML file called TestServerConfig.xml. Later this file will be edited to change server hostname, service port, configuration suffix, deployment URI, and cookie domain values to match with the production environment.

Configuring OpenSSO on the production server On the production server make sure that the following tasks are completed: •

Install the supported container and configure the OpenSSO web application with the data shown in the table

•

Configure the command line tool ssoadm in the production server

Once the preceding tasks are completed, log in to the administrative console and verify it is accessible.

[ 230 ]

Chapter 10

Adapting the test configuration data

The data obtained from the test server still contains the host name, service port, and other configuration data related to the test server. We need to change these test environment-specific data to match the production environment. Note that we are changing the data that are pertaining to the server configuration not the identity or authentication server details. If you have used a RADIUS server that was pointing to the test environment, you need to change this from the production server administration console. This kind of data will not be changed by this procedure, as the data only stores configuration details. The data is very sensitive to any typo as this could cause the server to fail. So let us take extreme caution while editing the file TestServerConfig.xml. To make things simpler I have created a sed script that would replace the appropriate values in the TestServerConfig.xml, so it can be imported to the production server using the ssoadm tool. Run the following command: sed -f test2prodn.sed /tmp/TestServerConfig.xml ProductionConfiguration.xml

> /tmp/

This will perform the necessary changes in the output file that can be loaded into the production system. The content of test2prodn.sed is the key to accomplish the test to production configuration conversion. The following is the content of the file with comments that explain what each one does. Due to formatting some lines are wrapped but when you make the script make sure each line is entered as complete instead of wrapping. Each uncommented line should start with a letter s (stands for string substitute): #change the old suffix to newsuffix s/o=oldsuffix.com/o=newsuffix.com/g s/oldsuffix.com/newsuffix.com/g #change the server port to new port s/com.iplanet.am.server.port=8080/com.iplanet.am.server.port=9090/g #changing the hostname:port pair to new value s/oldhost.packt-services.net:8080/newhost.new-services.com:9090/g s/oldhost.packt-services.net/newhost.new-services.com/g #change the domain cookie value/org alias s/packt-services.net/new-services.com/g #change the deploy uri to new s/\&\#47\;olduri/\&\#47\;newuri/g s/\"olduri/\"newuri/g #changing the configuration directory s/\&\#47\;export\&\#47\;ssouser\&\#47\;config-olduri/\&\#47\;export\&\ #47\;ssouser\&\#47\;config-newuri/g [ 231 ]

Backup, Recovery, and Logging #changing the bootstrap locations/bootstrap.file=\&\#47\;.*/bootstrap. file=\&\#47\;export\&\#47\;ssouser\&\#47\;.openssocfg\&\#47\;AMConfig_ export_ssouser_tomcat-9090_apache-tomcat-6.0.20_webapps_newuri_\/g

Importing into the production system

After successfully completing the foregoing section, the data has been modified to suit the production environment. Move the modified configuration data stored in the file /tmp/ProductionConfiguration.xml to the production server (newhost.newservices.com) and perform the following step to load into the production system: ./ssoadm import-svc-cfg -e thisisthesecretkey -X /tmp/ ProductionConfiguration.xml -u amadmin -f /tmp/pass Directory Service contains existing data. Do you want to delete it? [y|N] y Please wait while we import the service configuration... Service Configuration was imported.

Restart the server now and verify whether you are able to log in to the administration console. This completes the process of moving OpenSSO configuration from a test configuration to a production system. In each phase make sure that you take backups periodically. In case you fail at some point you will be able to go back to the previous step instead of starting all over. Remember that the passwords for the administrative users are kept identical in both test and production servers for simplicity.

OpenSSO audit and logging

In any enterprise, the product that is deployed in an IT environment to protect the resources must perform audit logging, so that at any given point an action can be traced back to the individual account that initiated that event. With more compliance standards evolution, and government agencies enforcement, vendors are forced to employ different mechanisms to collect data from the deployed system. These data will then be fed to industry standard tools to generate periodic reports for the security office. The importance of audit event logging has increased with recent new US and worldwide legislation mandating corporate and enterprise auditing requirements. Open source projects such as OpenXDAS, a Bandit project identity component, have begun to take their place in software security reviews as not only an improvement, but a requirement.

[ 232 ]

Chapter 10

Audit trails maintain a record of system activity by system or application processes and by user activity. In conjunction with appropriate tools and procedures, audit trails can provide a means to help accomplish several security-related objectives, including individual accountability, reconstruction of events, intrusion detection, and problem identification. It is important to distinguish between the audit logging that records the security actions performed by the user or system to accomplish a certain business case as opposed to the trace or debug logging that merely dumps the software execution code path along with associated data elements used at the runtime. The former is a requirement for the product to be deployed in the security realm where as the latter is only an optional feature to troubleshoot the system when a problem arises. In the OpenSSO server both types of logging are supported. Nevertheless audit logging has more advanced options to store even the records in a relational database system, such as MySQL. This facility is not available for the debug or trace logging.

Enabling debug (trace) level logging

In the out-of-the-box configuration, OpenSSO does not enable the trace level logging for obvious reasons including the system performance. Remember when you enable trace level logging, the system performance will degrade. An administrator can configure the server to output the trace level logging by simply setting the following property: ./ssoadm update-server-cfg -s http://newhost.new-services.com:9090/ newuri -u amadmin -f /tmp/.passwd_of_amadmin -a com.iplanet.services. debug.level=message

It is a hot swappable property that enables the OpenSSO server to recognize this change right away, without requiring to restart the web container. The valid values for this property are error (default), warning, and message. In the order of verbose level, there is another value off that disables the debug logging completely. The debug files will be placed under //debug. In this example, it will be under /export/ssouser/config-newuri/newuri/debug. The debug files can quickly grow huge, so please make sure that you disable the debug option as soon as you are done with the troubleshooting task. Typically the customer might want to enable debug logging for the following reasons: •

Troubleshooting complex problems especially after a customization

•

While debugging there are SSL/TLS or signing encryption issues

•

One of the OpenSSO service returns an incorrect status

[ 233 ]

Backup, Recovery, and Logging

For instance, if you are troubleshooting an authentication issue, it is wise to redirect all the debug events to a single file for tracing the sequence of steps in a logical manner. To achieve this, you should enable the property com.sun.services.debug.mergeall to ON, now all the debug events will be stored in a file named debug.out: ./ssoadm update-server-cfg -s http://newhost.new-services.com:9090/ newuri -u amadmin -f /tmp/.passwd_of_amadmin -a com.sun.services.debug. mergeall=ON

Unlike the audit log files, there is no log file rotation available for these debug files. The effect of above command can be achieved using the Admin console by navigating to Configuration | Servers and Sites | http://newhost.new-services. com:9090/newuri | Debugging. As you can see, it is a server instance-specific configuration, so you have to make this change in all the server instances. In the next chapter, you can learn more about troubleshooting and diagnostics.

Audit logging

The purpose of the audit logging is to provide a means for recording events that may be used to assign responsibility to actions occurring through the OpenSSO server. The audit log records allow the reconstruction of individuals' activities for assessment and auditing purposes. Any attempt to compromise the security of the system can easily be monitored. OpenSSO provides a well-defined log record format that can easily be interpreted and customized based on customer needs. Nevertheless, some of the physical security aspects of the log files or tables are expected to be provided by the system administrator utilizing features of the operating system (file permissions for file-based logging) or the RDBMS (for DB logging) of the system that the OpenSSO leverages for storing the log records. For instance, restricting the logging directory access permissions to 0700 (chmod), where the owner is the system user ID owning the web container process on which OpenSSO is deployed. If you are logging on to a database, then access to the DB's tables are expected to be restricted as prescribed by the underlying DB system's guidelines (MySQL/Oracle).

[ 234 ]

Chapter 10

As I mentioned earlier, all the OpenSSO services are defined by the sms.dtd compliant service called iPlanetAMLoggingService (amLogging.xml). This logging service fundamentally is an extension of the java.util.logging classes. Therefore, the OpenSSO logging service depends upon the facilities, provided those classes are interfacing with the operating system. Besides it also depends on the Service Management Service (SMS) for configuration information and the Policy Service to enforce access privileges to the logging services. This authorization enforces that only authorized principals have access to the audit records. When configured for database logging, the logging service relies on JDBC-compliant access to an Oracle or MySQL database server. In the case of flat file logging with intrusion detection enabled (also known as secure logging), it depends on a Java Key Store (JKS).

Enabling and disabling audit logging

In an out of the box configuration, the audit logging is enabled to use the file-based logging. The audit log records will be written in the /deploy-uri>/ log, for example, /export/ssouser/config-newuri/newuri/log. For some reason if you want to disable the audit logging, you can set the logging to INACTIVE by using the administration console interface (Configuration | System | Logging) or CLI: ./ssoadm set-attr-defs -s iPlanetAMLoggingService -t global -u amadmin -f /tmp/.passwd_of_amadmin -a logstatus=INACTIVE

When the logstatus property is set to INACTIVE, the logging level for all log files are set to level OFF. It is also possible to obtain a finer level of logging from the server by setting an appropriate value to the specific component for which you need a finer logging level. For example, amSSO.access contains all the session-related events. To get the finest level of logging, one can set iplanet-am-logging.amSSO. access.level=FINEST in the respective server configuration: ./ssoadm update-server-cfg -s http://opensso.packt-services.net:8080/ opensso -u amadmin -f /tmp/.passwd_of_amadmin -a iplanet-am-logging. amSSO.access.level=FINEST

This property format is for setting the logging level of individual log files, primarily in order to get more detailed logging information from a particular service or component. If the logstatus is ACTIVE and there are no individual log file logging level properties set in the server configuration, then the logging level set in the global logging (iPlanetAMLoggingService) service configuration is applied to all the log files. The individual log file's level will take precedence over the global logging settings. Changing the logging service's log level through the administration console or CLI takes effect immediately, hence you do not need to bounce the container.

[ 235 ]

Backup, Recovery, and Logging

File-based logging

OpenSSO logging can be stored in the local or NFS file systems. When the server is configured by default, it assumes that the flat file logging and the log files are written into the /deploy-uri>/log directory. The administrator can customize the location after configuring the server. The log files are named after the functional components with a suffix of .access or .error, the former containing all the access (read, write, and update) events and the latter containing the erroneous cases, such as failing events. You can look at the sample of the log directory contents that I have generated in a simple SSO scenario. There are more audit files that are not shown here. Those files will be generated based on the functionality being invoked, for example amSAML.access is not shown in the following screenshot:

As you might have noticed there are files that are indexed with numbers, for example amConsole.access-10. These indexes are created by the server due to a log rotation. The log rotation is the capability of the OpenSSO logging service where the administrator may configure the size of the each log file, when this pre-configured size is reached the log rotation happens. As each record is written to the log file, the total number of bytes written is checked against the configured maximum file size (iplanet-am-logging-max-file-size). If the maximum is met or exceeded, then file rotation occurs. During file rotation, the history files are pushed down by putting the contents of -(n-2) into -(n-1), and so on, until the contents of are written to -1, where n is the number of history files (iplanet-am-logging-num-hist-file). The oldest history file, -(n-1) is deleted, and a new is opened for writing the latest log records. [ 236 ]

Chapter 10

Logging location can easily be changed by using the administration console or the command line utility ssoadm. The following is the quickest way to change the logging location from default to /tmp/mylog: ./ssoadm set-attr-defs -s iPlanetAMLoggingService -t global -u amadmin -f /tmp/.passwd_of_amadmin -a iplanet-am-logging-location=/tmp/mylog

Again there is no need to restart the container, it takes effect right away.

Database logging

Flat file logging serves are good for the deployments where the number of users are relatively small in number. For the applications that are mission critical and require the highest level of security and availability, flat files may not be scalable for storage as well as data mining. There are log data analysis tools that are optimized to work with databases rather than flat files. OpenSSO does support database-based logging. This means the log events can be written to a pre-configured Oracle or MySQL database. At the time of writing OpenSSO did not support any other DB for logging. To configure the logging to a database, the administrator just needs to change the log location iplanet-am-logging-location to a valid database URL of the form jdbc:mysql://mysql.packt-services.net:3306/packtpub_ opensso?autoReconnect=true, if you are writing to a MySQL database. You can use the ssoadm tool to make the following configuration change in the server configuration: ./ssoadm set-attr-defs -s iPlanetAMLoggingService -t global -u amadmin -f /tmp/.passwd_of_amadmin -D /tmp/logging.txt

where the file /tmp/logging.txt contains the following: iplanet-am-logging-location=jdbc:mysql://mysql.packt-services. net:3306/packtpub_opensso ?autoReconnect=true iplanet-am-logging-db-user=dbuser iplanet-am-logging-db-password=dbsecret12 iplanet-am-logging-db-driver=com.mysql.jdbc.Driver iplanet-am-logging-type=DB

The autoReconnect=true is required for automatic reconnection after an idle timeout.

[ 237 ]

Backup, Recovery, and Logging

The preceding procedure will enable the OpenSSO to log the events into the MySQL database. The administrator must make sure that the MySQL JDBC drivers are properly copied (mysql-connector-java-5.1.10-bin.jar) into the WEB-INF/lib directory of the opensso.war application, otherwise the logging service will throw unable to load DB driver exceptions. For the command line tool to log the events into the database, the driver location must be added into the ssoadm script after removing the property -Dcom.sun.identity.log.dir. This property needs to be removed to enable the logging for ssoadm to occur at the server side into the database. When database logging is specified, the com.sun.identity.log.handlers. DBHandler and com.sun.identity.log.handlers.DBFormatter classes are employed. Upon instantiation, if logging is enabled the DBHandler uses the database's URL (iplanet-am-logging-location), database user (iplanet-am-logging-db-user), password (iplanet-am-logging-db-password), and JDBC driver (iplanet-amlogging-db-driver) to establish a connection to the database server. The supported JDBC driver names are distinctive enough to determine whether the target database server is Oracle (contains "oracle") or MySQL (contains "mysql"). With the connection to the database established, the table (equivalent to log file) is created, if it does not already exist. Unlike the filenames in flat file logging, the periods (.) are not valid characters for table names in database logging. The periods are converted into underscores (_). Also, the Oracle database uses table names in all uppercase characters. The following is a screenshot of the tables that are created after setting the logging configuration to MySQL. This is only a part, there are more tables for each functional components that will be created when the functionality is exercised.

[ 238 ]

Chapter 10

Two other differences between flat file and DB logging concern the log record columns (DB equivalent for the log record "fields"). While the entire log record is text in flat file logging, the individual columns in DB logging can be created with different data types. In particular, the "time" column is created as a data type native to the DB ("datetime" for MySQL, "date" for Oracle), and the "Data" column is created as data types with large capacities ("LONGTEXT" for MySQL, "CLOB" for Oracle). The remainder of the log record columns are short in length, so they are created as "varchar" (or "varchar2" for Oracle) types with maximum lengths of 255 characters. New tables are created with all the possible columns. If the table exists and is missing any columns, the table is altered to add the missing columns. The following screenshot shows the typical names of the log database tables for OpenSSO when configured to log in to Oracle DB:

The following command configures the OpenSSO server to write its log events to a pre configured Oracle DB: ./ssoadm set-attr-defs -s iPlanetAMLoggingService -t global -u amadmin -f /tmp/.passwd_of_amadmin -D /tmp/orcl.logg.txt

[ 239 ]

Backup, Recovery, and Logging

The file contents of /tmp/orcl.logg.txt contains the following attribute value pairs. As you might have guessed the string orcl denotes the DB instance name. Like the MySQL logging, you need to make sure that the JDBC drivers (ojdbc5.jar) are copied into the OpenSSO application and the ssoadm script is updated to include the database drivers: iplanet-am-logging-location=jdbc:oracle:thin:@oracledb.packt-services. net:1521:orcl iplanet-am-logging-db-user=dbuser iplanet-am-logging-db-password=dbsecret12 iplanet-am-logging-db-driver=oracle.jdbc.driver.OracleDriver iplanet-am-logging-type=DB

Remote logging

The OpenSSO server supports remote logging. This allows a remote client application using the OpenSSO client SDK such as the policy agents, or another OpenSSO server (in the same deployment) to use an OpenSSO server's logging services. The logging service is available only to trusted servers and authorized users. An arbitrary user or server cannot write into the logging service. If the OpenSSO server wishes to use another OpenSSO server as its logging service server, then the following two conditions must be met: •

The source server must be trusted by the target OpenSSO server that provides logging service

•

The source server's logging service URL must point to the target server's logging service URL

Typically, a policy agent can be configured to perform remote logging to the server.

Secure logging

Secure logging is a powerful feature that helps to prevent the intrusion and tampering of files that hold the logged security events. This works in association with the flat file logging. In the security arena the accountability for any action is determined from the trace log and audit events. If someone can change the events file, for example remove a malicious event without proper authorization, then it should be considered as a security breach. Customers can deploy a secure logging feature to prevent these kinds of unauthorized malicious activities.

[ 240 ]

Chapter 10

This optional feature adds additional security to the logging function. Secure logging is accomplished by using a pre-registered certificate configured by the system administrator. A Manifest Analysis and Certification (MAC) is generated and stored for every log record. A special signature log record is periodically inserted that represents the signature of the contents of the log written to that point. The combination of the two records ensures that the logs have not been tampered with. There are two methods to enable secure logging, namely, through a Java Cryptography Extension (JCE) provider and through a Java Security Server (JSS) provider. Enabling secure logging in the OpenSSO server is a three step process, which is as follows: •

Create the keystore to sign the logs

•

Configure the logging service to turn ON the secure logging

•

Verify the log archives

Creating the keystore

Before employing the secure logging feature, you should first create a keystore that will sign the log archives. You can use the keytool that is bundled with Java SDK: $JAVA_HOME/bin/keytool -genkey -alias Logger -keyalg DSA -sigalg SHA1withDSA -keysize 1024 -dname "cn=Logger,ou=identity,o=packtservices,c=us" -storetype jks -keystore OpenSSOLogger.jks -storepass secret12

The keystore password for the secure logging certificate store must be the same as of the top level administrator user amadmin.

The preceding command will create the keystore named OpenSSOLogger.jks. This file can be used while configuring the secure logging service. The keystore creation process is not complete unless the following steps are completed. Let's generate a certificate signing request (CSR) that can be signed by a Certificate Authority (CA): $JAVA_HOME/bin/keytool -certreq -alias Logger -storetype jks -keystore OpenSSOLogger.jks -storepass secret12 -file /tmp/certreq.txt

The certificate request is available in the file /tmp/certreq.txt. This file can be submitted to a valid CA to obtain the certificate.

[ 241 ]

Download from Wow! eBook

Backup, Recovery, and Logging

The new certificate that you get from the CA should be added into the key store to complete the keystore creation process. Your CA will issue two certificates, namely, a trusted CA certificate and a certificate in response to your CSR. First load the CA certificate followed by the signed certificate: $JAVA_HOME/bin/keytool -import -keystore OpenSSOLogger.jks secret12 -trustcacerts -file /tmp/cacert.txt

-storepass

$JAVA_HOME/bin/keytool -import -keystore OpenSSOLogger.jks secret12 -alias Logger -file cert.txt

-storepass

Once the preceding steps are completed without any errors, then you can go ahead and configure the logging service to enable the secure logging as follows: ./ssoadm set-attr-defs -s iPlanetAMLoggingService -t global -u amadmin -f /tmp/.passwd_of_amadmin -D /tmp/secure.logging

The file /tmp/secure.logging contains the following: iplanet-am-logging-secure-certificate-store=/export/ssouser/ opensso-8080/OpenSSO/Logger.jks iplanet-am-logging-security-status=ON iplanet-am-logging-type=File iplanet-am-logging-location=/export/ssouser/opensso-8080/securelog iplanet-am-logging-secure-signing-algorithm=SHA1withDSA

How to verify

Once the server is configured for secure logging, you can use the amverifyarchive utility to verify the integrity of the log archives: ./amverifyarchive -l WSFederation.access -p /export/ssouser/opensso-8080/ securelog -u amadmin -w secret12 Archive Verification : no files to verify, keyFiles.length == 1 Verification of Log Archive for WSFederation.access passed Successfully.

Now let us open amSSO.access, add some characters, and save it. Then run the following: ./amverifyarchive -l amSSO.access -p /export/ssouser/opensso-8080/ securelog -u amadmin -w secret12 File being verified : _secure.amSSO.access.20052010215433 Signature Verification Failed in file :_secure.amSSO. access.20052010215433=at record no : 1 Verification of Log Archive for amSSO.access failed. Intrusion Detected.

As you can see the verification of the archive failed due to a signature mismatch.

[ 242 ]

Chapter 10

Summary

It is very critical to safeguard the configuration data to reconstruct the system from unexpected system crashes. It is also good practice to periodically backup the system for archival and audit purposes. We have discussed more than one option to perform the backup and recovery process. OpenSSO provide two major types of logging to capture the system and user events for auditing purposes. One can use RDBMS or a simple file-based logging, for improved security. Secure logging can be employed to prevent the intrusions and unauthorized tampering of audit log files. In the next chapter, we will be dealing more with the debug or trace level logging in detail. The diagnostic tool is introduced as a part of the OpenSSO ZIP file that can be configured on the Glassfish server. There are many troubleshooting tips provided in the next chapter that will help you to fix your server, in case you are stuck at some point.

[ 243 ]

Troubleshooting and Diagnostics The OpenSSO server is simple to configure and use as long as everything is going well, but when it fails at some point during configuration or later, things are going to get messy due to the nature of its multiple intra components interaction. So debugging and troubleshooting does require a methodical approach to identify the problem area. In this chapter, let us look at some of the common problem areas and some tips on how to troubleshoot them with minimal resources. I will also highlight the salient features of the OpenSSO diagnostic tool, which is a graphical user interface to diagnose the configuration and deployment of the OpenSSO servers. The scope of the chapter is not to go over every aspect of the problem, but to give you an idea of where the problem would be. In essence, we will cover the following: •

OpenSSO diagnostic tools

•

Specific erroneous scenarios along with possible causes

•

Tips to debug and troubleshoot issues

OpenSSO diagnostic tools

The diagnostic tool is bundled along with the opensso.zip archive. After uncompressing the archive you will be able to find the diagnostic tool ZIP archive under opensso/tools/ssoDiagnosticTools.zip. To obtain the script ssodtool. sh you should unzip the ssoDiagnosticTools.zip. This will lay out the required jars and binaries in order to invoke the diagnostic tool user interface. This tool facilitates in uncovering any potential deployment and configuration problems as opposed to identifying the runtime failures such as the encryption failure.

Troubleshooting and Diagnostics

Installing and configuring the tool

There are no special set up or configuration procedures required to use this tool. It is ready for use as soon as you unzip the ssoDiagnosticTools.zip from the opensso.zip archive file. This tool implementation follows a plugin architecture model. Consequently, one should be able to build custom diagnostic tool plugins for new services that can be seamlessly integrated with the existing services (http://wikis.sun.com/display/OpenSSO/The+OpenSSO+Diagnostic+Tool).

Invoking the tool

This tool supports both graphical user interface and a console interface where customers can invoke on a headless machine. On Unix systems the shell script could be invoked as follows: [ssouser@opensso]:~/opensso/tools/diag>./ssodtool.sh Invoking GUI Please wait while system initializes... GUI initializing Begin !!! GUI initializing End !!! Press to stop the Diagnostic Tool

Alternatively the console version of the tool can be brought up by using the --console option along with the script name: [ssouser@opensso]:~/opensso/tools/diag>

./ssodtool.sh --console

Invoking CLI Diagnostic Tool>help Usage: ssodtool agents|reports|web-container|tamper-detection|sample|conn ectivity|system|server [OPTIONS] OPTIONS: -h, --help The help command displays a list of options available. To display the options of each command, use the following syntax: ssodtool command_name --help | -h

The console version would be very useful when you cannot find a suitable display for the host from where you are invoking the tool, besides this option could be used to automate certain diagnostic and metrics collection processes. Nevertheless, the graphical user interface is very intuitive for the end user. On the Windows operating system the whole thing can be achieved by invoking the batch script ssodtool.bat. The rest of the options hold good for the batch script as well. [ 246 ]

Chapter 11

Currently this tool can verify and validate most of the core configuration problems in the OpenSSO server deployed on the following containers: •

Oracle Glassfish Server

•

Oracle iPlanet Webserver 7.0

•

Oracle Weblogic Server 10.3

•

IBM WebSphere 7.0

The rest of the containers, such as Apache Tomcat, are not supported for this tool even though the server deployment is supported on this container. When you invoke the tools in the graphical mode, you will notice a screen that is asking for some of the pertinent details of the OpenSSO server and the web container configuration directory. As you can see from the screenshot, multiple levels of verification is done using this tool including verifying the server connection. The following is the sample view of how the verification screen appears. You can select more than one test in sequence to verify the sanity of the system.

[ 247 ]

Troubleshooting and Diagnostics

Troubleshooting

Like I mentioned earlier, the diagnostic tool will not identify any runtime issues that might occur during the runtime processing. The runtime issues could emanate from various sources including incorrect input data, insufficient system resources, and so on and so forth. In the next several sections let us discuss how to debug and troubleshoot the runtime problems by quoting specific issues. Before even attempting to search for solutions on Google, please make sure you have done a decent level of debugging on your configuration. Typically, when something fails, you should look for clues in the following files: •

OpenSSO debug logs

•

OpenSSO audit logs

•

Web Container's logs

OpenSSO audit logs are by default turned on and available for you to view under the //log directory. Whereas the debug logs are not turned on for apparent performance reasons in the out of the box configuration. When you have run into problems, the first thing you would do is to turn on the debug logs by setting the following property using the admin console or by means of ssoadm CLI: ./ssoadm update-server-cfg -s http://opensso.packt-services.net:9090/ opensso -u amadmin -f /tmp/.passwd_of_amadmin -a com.iplanet.services. debug.level=message

This will cause the server to run in debug mode; the value message means (for the property com.iplanet.services.debug.level) the highest level of verbose possible by the server. This will dump the entire conversation between the server components and clients in the debug files located under the //debug directory. In this case all the debug logs will be written into multiple files based on the functional components. For example, authentication-related debug logs will be stored in the file named Authentication. Categorizing the debug information is good but storing the debug logs in multiple files complicates the debug process as it is difficult to correlate the events at a given timestamp. To make the debug process more simple, one can configure the system to write all the debug logs into a single file by enabling the following property: ./ssoadm update-server-cfg -s http://opensso.packt-services.net:9090/ opensso -u amadmin -f /tmp/.passwd_of_amadmin -a com.sun.services.debug. mergeall=on

This enables the server to consolidate the debug messages into a single file, debug. out, so the administrator can look into one file to extricate the sequence of events that occurred at any given time frame. [ 248 ]

Chapter 11

In general, both of these properties are hot swappable, so there is no need to restart the web container that hosts the OpenSSO web application. In the next section, let us discuss some specific problematic scenarios and the tips to debug them.

Installation and configuration

We'll consider a few scenarios to discuss what could go wrong here.

Scenario 1

Symptom: While configuring the OpenSSO server the configurator failed, with the following message: The application encountered an unexpected error: [#|2010-08-13T15:21:05.955-0700|INFO|glassfish3.0.1|javax.enterprise. system.std.com.sun.enterprise.v3.services.impl|_ThreadID=24;_ ThreadName=Thread-1;|amSDK:08/13/2010 03:21:05:954 PM PDT: Thread[http-thread-pool-8080-(2),10,Grizzly] ERROR: Crypt: failed to set password-based key java.security.NoSuchProviderException: no such provider: SunJCE atsun.security.jca.GetInstance.getService(GetInstance.java:66) at javax.crypto.SunJCE_b.a(DashoA13*..)

Possible Causes: These kinds of issues are common in the configuration phase of the OpenSSO server, sometimes this will happen during the authentication time as well. In this case the cause for the failure is relatively apparent as it complains about the SunJCE provider not being found. As this provider comes from the JDK it could not find the SunJCE provider in its $JAVA_HOME/jre/lib/security/java.security file. There is an exception for this when it comes into IBM Java Virtual Machine, which will be discussed shortly. Tips for Troubleshooting: IF you are using Sun JDK then to fix this issue, add the SunJCE provider to the top of the list of providers. If it already exists, make sure that it is on top of the list, as follows: security.provider.1=com.sun.crypto.provider.SunJCE security.provider.2=sun.security.rsa.SunRsaSign security.provider.3=com.sun.net.ssl.internal.ssl.Provider security.provider.4=sun.security.provider.Sun security.provider.5=sun.security.jgss.SunProvider security.provider.6=com.sun.security.sasl.Provider security.provider.7=org.jcp.xml.dsig.internal.dom.XMLDSigRI security.provider.8=sun.security.smartcardio.SunPCSC

[ 249 ]

Troubleshooting and Diagnostics

Scenario 2

It is easy to configure an already existing OpenSSO system to run in "debug" mode, but what if the system is being configured and you want to view the debug traces of OpenSSO? There is a way to do that in OpenSSO. It is always useful to get the debug information of the configurator, especially if things are not moving well. When you encounter problems with OpenSSO while configuring them, just add the following Java VM options into your containers' Java virtual machine: -D"com.iplanet.services.debug.directory=/tmp/debug" -D"com.iplanet.services.debug.level=message"

After adding these parameters restart the container and invoke the OpenSSO configurator. Now you should be able to view the debug logs from the /tmp/debug directory. This is one quick way to debug the configurator-related problems.

Scenario 3

Symptom: Configuration of OpenSSO was successful without login problems. However, after restarting the login page returned the configuration page. Possible Causes: When this happens, either the bootstrap file has been removed or is not readable by the web container's Java virtual machine process. Tips for Troubleshooting: In order to recover back you should check a couple of things: •

Ensure the configuration directory is indeed present in the file system

•

Ensure the configuration directory and the bootstrap file is readable by the web container's JVM process

•

Ensure the external configuration store (in the case of the configuration store is ODSEE) is up and running

•

Ensure the OpenSSO server is not running out of resources such as file descriptors, process limits, and so on

It is not uncommon that once you restart the JBOSS application server, subsequent access to the OpenSSO server will show you the configurator page. Do not panic, this is something known, this is due to the ServletContext.getRealPath() method which does not always return the same value after the server is restarted.

[ 250 ]

Chapter 11

How to Fix

To fix this problem edit the /server/default/deploy/ opensso.war/WEB-INF/classes/bootstrap.properties file and update the property configuration.dir= where is the directory that contains the bootstrap file. After performing the preceding step, restart the JBOSS server and you will be able to see the login page from OpenSSO. You can also use this property when the system user that is running the web/application server process does not have a home directory, that is, System.getProperty(“user.home") returns null.

Scenario 4

Symptom: OpenSSO web application deployed successfully, but failed to initialize with the following exceptions: [#|2010-09-04T16:43:47.708-0700|SEVERE|sun-appserver2.1|com. sun.jersey.core.spi.component.ProviderFactory|_ThreadID=16;_ ThreadName=Timer-6;_RequestID=94ec2927-49ac-495f-97ad42bf54b1fbe2;|The provider class, class com.sun.jersey.core. impl.provider.xml.XMLStreamReaderContextProvider, could not be instantiated. Processing will continue but the class will not be utilized java.security.AccessControlException: access denied (java.lang. reflect.ReflectPermission suppressAccessChecks) atjava.security.AccessControlContext.checkPermission(AccessContro lContext.java:323) at java.security.AccessController.checkPermission(AccessControll er.java:546) at java.lang.SecurityManager.checkPermission(SecurityManager. java:532) at java.lang.reflect.AccessibleObject. setAccessible(AccessibleObject.java:107) atcom.sun.jersey.core.spi.component.ComponentInjector$2. run(ComponentInjector.java:143)

Possible Causes: These kinds of exceptions happen when the Java EE security is enabled in the container. Tips for Troubleshooting: You can add the necessary Java EE permissions as documented in the OpenSSO guide to overcome this problem. One can also disable the Java EE security manager to troubleshoot when the problem is really with the security permissions.

[ 251 ]

Troubleshooting and Diagnostics

Authentication and session areas

There are many conditions that could trigger a runtime error in these components. Let us see some of the very common errors that occur in the authentication and session areas.

Scenario 1

Symptom: Authentication keeps on failing even though the user ID and password are correct. Possible Causes: There could be more than one user ID matching, for the given username. The LDAP authentication module configuration could be wrong, including incorrect LDAP server name/port, SSL handshake error, or a wrong search scope/base. Tips for Troubleshooting: Make sure you properly configured the LDAP module to rule out the above possibilities. If there is more than one username matching, then enable the username uniqueness in the underlying LDAP server.

Scenario 2

Symptom: OpenSSO server keeps on showing the login page even after submitting the valid user and credentials. Possible Causes: Most likely this could be a browser or OpenSSO platform service cookie domain-related configuration issue. Tips for Troubleshooting: Check your browser setting for JavaScript and cookie settings. Both should be enabled for the login process to be successful. For example, in some newer versions of Internet Explorer, JavaScript is not enabled in the default configuration. Next, check your platform service configuration to make sure it has a proper cookie domain value with a dot(.) prefix or a hostname if you are running on a standalone host.

Scenario 3

Symptom: Windows NT authentication keeps on failing. Possible Causes: This kind of failure happens mostly due to an issue in the connectivity between the OpenSSO server and the backend Windows domain.

[ 252 ]

Chapter 11

Tips for Troubleshooting: While debugging these kinds of issues first make sure the connection between the OpenSSO server and the Windows NT is working properly. This can be done in a simple way by just pinging, to actually verify the Samba Client connectivity to the Windows Active Directory domain. There is a wealth of information available for troubleshooting the Windows Desktop SSO module (found at. http://wikis.sun.com/display/OpenSSO/Troubleshooting+OpenSSO+Enterp rise+8.0+Windows+Desktop+SSO). In order to debug the NT authentication issues, please follow these check lists:



•

Ensure the smbclient binary is available under //bin.

•

Execute the smbclient -W domainame -L hostname -U ntuser%passwd. For example: smbclient -W AMQA

-L ad-host

-U andy%secret993

This should be successful with no errors despite all the NT authentication failures, then it must be OpenSSO issue that needs to be debugged.

Scenario 4

Symptom: When the sessions are viewed from the session tab, some of the sessions show negative session time values, especially for the especially in the session failover setup. Possible Causes: This kind of scenario could occur when one or more of the servers in the site are not properly time-synchronized with the other servers. Tips for Troubleshooting: First ensure that the OpenSSO servers in the site are properly time-synchronized either through the NTP protocol or manually.

Identity repository and password reset A few scenarios that are possible here are:

Scenario 1

Symptom: I have added a custom attribute and objectclass in the backend LDAP server. I then created a new identity repository for the plugin in the OpenSSO, but when I try to create a user it does not contain the new attribute and objectclass. Similarly, I could not get this attribute retrieved from the OpenSSO clients, such as agents or REST calls.

[ 253 ]

Troubleshooting and Diagnostics

Possible Causes: It could be a configuration issue. Either you have not added these custom attributes to the identity repository plugin configuration or there could be a typo in the attribute names, or else the underlying LDAP server does not allow these attribute values to be read. Tips for Troubleshooting: First make sure the attributes have been added to the configuration and spelt correctly. If it still does not work, look out for any ACIs that are blocking the attributes being queried by the LDAP clients. The user in the identity repository plugin configuration should be able to search for these custom attributes.

Scenario 2

Symptom: While performing identity repository-related operations the server returned the following response: Plug-in com.sun.identity.idm.plugins.ldapv3.LDAPv3Repo encountered an ldap exception. LDAP Error 65: The requested operation will add or change data so that the data no longer complies with the schema.

Possible Causes: This message is thrown mainly due to a LDAP schema violation in the backend identity repository. Tips for Troubleshooting: OpenSSO server reads the IdRepo configuration, and based on this configuration, it tries to perform a ADD/MOD/DEL/SRCH operation in the backend LDAP server. This message will appear only when ADD or MOD operation is attempted. When this message appears you should check the LDAP server to see whether schema exists for the attributes you are trying to set from OpenSSO. Consider checking for typos in the attribute names as well.

Scenario 3

Symptom: Customer updated the attributes of an identity in the identity repository, but the changes are not shown in the administration console of the OpenSSO. Possible Causes: Mostly this is due to the change notification issue. Tips for Troubleshooting: In the IdRepo configuration there is a persistent search notification configuration item present, please check whether this property and the associated properties are set with a legitimate value for the IdRepo to submit a psearch request to the LDAP server. It is also possible sometimes that the backend LDAP servers could have maxed out the persistent search connections. In any case, the debug file IdRepo will contain the details of the persistent connections that were submitted to the LDAP server.

[ 254 ]

Download from Wow! eBook

Chapter 11

Scenario 4

Symptom: Customer received the following message after attempting to reset the forgotten user password: Password Reset Confirmation Could not connect to SMTP host: localhost, port: 25; nested exception is: java.net.ConnectException: Connection refused

Possible Causes: These kinds of messages typically indicate that the password reset application configuration is not set properly at the server side. The SMTP host name or port could be wrong. Tips for Troubleshooting: Login to the administration console and check the SMTP port and the host name for the respective realm. It should be pointing to a valid SMTP server and port. If this is correct, then check whether the SMTP server and port are accessible from the OpenSSO server.

Scenario 5

Symptom: Customer received the following message when trying to reset the end user password from the OpenSSO password reset web application: Password Reset Confirmation Your password has been reset but we are unable to send it to you. Contact your administrator.

Possible Causes: These kinds of message will be shown in the browser when the end user does not have a valid e-mail address in their profile, or a runtime error could have occurred while attempting to send the password to the user's e-mail address. Tips for Troubleshooting: First check the concerned user's profile for the existence of a valid e-mail address. If it is present, then you probably should check the SMTP server configuration. Try to send a test mail using a common mail client such as mailx.

Policy and agents

In the Policy and agents area most of the issues could be resolved by time synchronizing between the OpenSSO server and agent hosts. There may otehr scenarios where the agent or server could run it to problems. The next few scenrios high light the common problems.

Scenario 1

Symptom: Protected resource not accessible, the browser keeps on looping between the OpenSSO server and the agent. [ 255 ]

Troubleshooting and Diagnostics

Possible Causes: There are many reasons why one could run into these scenarios. It is basically because the server and agents could not communicate reliably due to a configuration issue. Tips for Troubleshooting: The fault could be in the agents or server configuration or both. You could check the following: •

Ensure both server and agents are in the same domain. If they are in different domains, CDSSO should have been enabled.

•

Make sure the protected URL is a FQHN (fully qualified host name).

•

Make sure the browser is accepting the cookie.

•

Clear the cookies in the browser and retry.

•

Ensure that proper cookie encoding is enabled for certain containers.

•

Make sure the domain cookie value is set with a prefixed dot in the serverside platform service.

Scenario 2

Symptom: Customers noticing the following error after successful agent installation: Exception starting filter Agent java.lang.ClassNotFoundException: com.sun.identity.agents.filter. AmAgentFilter at org.apache.catalina.loader.WebappClassLoader. loadClass(WebappClassLoader.java:1498) at org.apache.catalina.core.ApplicationFilterConfig.getFilter(Applicat ionFilterConfig.java:235) at org.apache.catalina.core.ApplicationFilterConfig.setFilterDef(Appli cationFilterConfig.java:369) at org.apache.catalina.core.ApplicationFilterConfig.(Application FilterConfig.java:103) at org.apache.catalina.core.StandardContext. filterStart(StandardContext.java:4381) at org.apache.catalina.core.StandardContext.start(StandardContext. java:5181) at com.sun.enterprise.web.WebModule.start(WebModule.java:327)

Possible Causes: Agent installer did not place the required JARs in the configuration folder due to permissions issues, or the configuration changes made by agent installation could have been overwritten.

[ 256 ]

Chapter 11

Tips for Troubleshooting: You can check in the domain.xml/server.xml for the agents-related JARs in the classpath. Also make sure the proper server instance block has the agents JARs. In the glassfish server there are two configurations, one for the administration server, and the other for the customer applications. One should choose the correct instance to install the agents. Also if the domain is running during agent installation, then the changes made by agent installer will be overwritten the next time the glassfish server is restarted.

Scenario 3

Symptom: My agents and server are configured perfectly, but the protected resources are always denied even though the customer is using the correct subject and condition. Possible Causes: This could be due to time-synchronization issues between the agents and servers. Tips for Troubleshooting: Check whether the OpenSSO server and the agent's machines are time-synchronized by means of a standard protocol such as NTP. You can also view the agent-side debug logs to see what the policy server response was.

Command line tools

In the next few sections discuss some of the frequently encountered issues in the command line area including the ssoadm tool.

Scenario 1

Symptom: When the ssoadm tool is invoked, the customer receives the following message: com.sun.identity.cli.CLIException: AdminTokenAction: FATAL ERROR: Cannot obtain Application SSO token. Check AMConfig.properties for the following properties com.sun.identity.agents.app.username com.iplanet.am.service.password at com.sun.identity.cli.LogWriter.log(LogWriter.java:109) at com.sun.identity.cli.Authenticator.ldapLogin(Authenticator. java:169) at com.sun.identity.cli.AuthenticatedCommand. ldapLogin(AuthenticatedCommand.java:158) at com.sun.identity.cli.serverconfig.ListServers. handleRequest(ListServers.java:59) at com.sun.identity.cli.SubCommand.execute(SubCommand.java:290) at com.sun.identity.cli.CLIRequest.process(CLIRequest.java:212) at com.sun.identity.cli.CLIRequest.process(CLIRequest.java:134) [ 257 ]

Troubleshooting and Diagnostics at com.sun.identity.cli.CommandManager.serviceRequestQueue(CommandMan ager.java:568) at com.sun.identity.cli.CommandManager.(CommandManager.java:164) at com.sun.identity.cli.CommandManager.main(CommandManager.java:141) AdminTokenAction: FATAL ERROR: Cannot obtain Application SSO token. Check AMConfig.properties for the following properties com.sun.identity.agents.app.username com.iplanet.am.service.password

Possible Causes: This issue may be due to the fact that the OpenSSO server is not directly accessible by the ssoadm tool. Most likely the servers are behind a load balancer or a firewall. Tips for Troubleshooting: You may want to try the option suggested in Chapter 2. That is use of -D"com.iplanet.am.naming.map.site.to.server".

Scenario 2

Symptom: While invoking the setup program or ssoadm tool (or the amverifyarchive or ampassword utility) in the IBM Java environment, the following exception is thrown: Failed to create debug directory java.security.NoSuchProviderException: no such provider: SunJCE atsun.security.jca.GetInstance.getService(GetInstance.java:82) at javax.crypto.b.a(Unknown Source) at javax.crypto.SecretKeyFactory.getInstance(Unknown Source) atcom.iplanet.services.util.JCEEncryption. setPassword(JCEEncryption.java:369) atcom.iplanet.services.util.Crypt.createInstance(Crypt. java:126) at com.iplanet.services.util.Crypt.initialize(Crypt.java:97) at com.iplanet.services.util.Crypt.(Crypt.java:89)

Possible Causes: Unlike the previous one that we have discussed in the beginning of this chapter this one is specific to IBM Java, and that has to be fixed in a different manner as described in the following section. Tips for Troubleshooting: In this scenario it is very clear that the problem was due to the missing Sun JCE provider, but we can force the tool to use the IBMJCE provider by adding the following JVM options in the script: -D"amCryptoDescriptor.provider=IBMJCE" -D"amKeyGenDescriptor.provider=IBMJCE"

[ 258 ]

Chapter 11

Summary

In this chapter, we have discussed how one can troubleshoot the configuration and deploy problems by using the OpenSSO diagnostic tools. This tool provides a means to identify and isolate the static configuration and deployment issues. Sans this tool identifying the root cause of the problems could have been cumbersome. At the same time, diagnostic tools cannot identify the dynamic problems that occur due to various runtime factors. We have seen some of the typical issues that could happen in the runtime and how to fix them. They are only samples, and do not constitute all of the problems that could possibly occur in the OpenSSO deployment. Nevertheless, the tips that were postulated in this chapter should help you to perform an orderly troubleshooting of a problematic OpenSSO server.

[ 259 ]

Index A Access Control tab about 70 agents 81, 82 authentication 71 data store 73 general 71 policies 77, 78 privileges 74-76 service 72, 73 subjects 79, 80 access management 16, 77, 78 Access manager repository plug-in about 143, 186, 193 data store, creating for 194 data store, deleting 196 data store properties, displaying 195 data store properties, updating 196 removing 196 account lockout, attributes inetuserstatus 138 iplanet-am-user-account-life 138 iplanet-am-user-login-status 138 nsaccountlock 138 account lockout, OpenSSO about 138 configuring 138, 139 in-memory lockout 141 physical lockout 140 action parameter 214 Active Directory 115 add-auth-cfg-entr command 107 administration interfaces, OpenSSO 64 administrative console accessing 65, 66

agent configuration scenarios 255, 257 agent identities creating 218 deleting 221 agent profiles about 82 creating 82, 159 agents searching for 216 AgentsRepo plugin 187 amSDK. See  Access manager repository plug-in AMSDKRepo plugin 188 Anonymous module 116 Apache Tomcat 6.0.20 configuring 31-33 installing 31-33 Apache Tomcat container 22 appid parameter 213 arg parameter 105 attributes adding, to amUser.xml file 88, 89 audit logging about 234 disabling 235 enabling 235 need for 234, 235 audit trails 233 authenticate interface invoking 210 authentication 71, 95 authentication and session scenarios 252, 253 authentication chain about 111

creating 112 deleting 114 reading 113 updating 112 using 113 authentication instance creating 108 deleting 110 reading 109, 110 updating 109 using 110 authentication modules, OpenSSO Active Directory 115 Anonymous 116 Certificate (X.509) 116-119 Core 124 data store 115 HOTP 121 HTTP basic 120 JDBC 120, 121 LDAP 115 Membership 120 RADIUS 122 SafeWord 122 SecurID 122 Unix 123 Windows Desktop SSO 124 Windows NT 123 authentication protocol, OpenSSO LDAP 108 authentication service 95-97 authentication types, OpenSSO level 100 module 99, 100 realm 101 resource 102 role 101 service 100 user 101 authentication URL parameters, OpenSSO about 103 arg 105 ForceAuth 106 goto 103, 104 gotoOnFail 104 IDToken 103 iPSPCookie 106

locale 104, 105 PersistAMCookie 107 authorization 214 authorize method about 214 parameters 214 authorize method, parameters action 214 subjectid 214 uri 214

B backup about 223 benefits 223 recovering, operations 223 bootstrap file 224 bootstrap locator file 39 brute force attack 137 BSD-style license 200

C caching 188 CDSSO 155 certificate revocation lists. See  CRL certificate signing request. See  CSR Certificate (X.509) 116-119 client 207 CLI tool 64 command line configurator OpenSSO, configuring 56, 57 command line tool groups, managing from 81 scenarios 257, 258 users, managing from 80 condition 156 configuration, account lockout 138, 139 configuration change performing 229 configuration data backing up 224, 226 configuration, diagnostic tools 246 configuration directory, OpenSSO 46, 47 configuration files backing up 225 configuration, OpenLDAP server 200, 201 [ 262 ]

configuration, OpenSSO server scenarios 249, 250, 251 configuration store about 24 embedded configuration store 25, 26 versus identity store 24 configuration tab about 83 server configuration properties, removing 85 server configuration properties, updating 84, 85 server properties, retrieving 84 console customization, OpenSSO about 86 LDAP schema, extending 87 cookies 97 core authentication module about 124 user profile attributes, setting in SSO token 126, 127 user profile requisites 124, 125 crash recovery 227, 228 create-auth-cfg command 107 create-auth-instance command 107 CRL 117 Cross-domain SSO. See  CDSSO CRUD 65 CSR 241 curl utility 208 custom authentication modules adding 128

D database logging about 237, 238 versus flat file logging 239 data store about 73 creating, for Microsoft Active Directory 199 creating, for Microsoft Active Directory Application Mode (ADAM) 199 creating, for OpenDS 198 creating, for OpenLDAP 200 creating, for Oracle DSEE 197, 198 creating, for Tivoli DS 199

deleting 196, 198 streamlining 202 testing 203 updating 198 data store authentication module 115 data store, creating for Microsoft Active Directory 199 for Microsoft Active Directory Application Mode (ADAM) 199 for OpenDS 198 for OpenLDAP 200, 203 for Oracle DSEE 197, 198 for Tivoli DS 199 delete-auth-cfgs command 107 delete-auth-instances command 107 demilitarized zones (DMZs) 97 Denial of Service. See  DOS deployment requisites, OpenSSO web application about 22 browser requisites 24 containers 22 disk and memory requisites 23 Java SDK support 23 operating systems support 22 diagnostic tools, OpenSSO about 245 configuring 246 installing 246 invoking 246, 247 Directory Information Tree(DIT) 187 distributed authentication (DA) 97 DOS 95, 137 dsconfig utility 149

E embedded configuration store about 25, 26 used, for multi server configuration 50 used, for single server configuration 40-46 entitlements service 15, 18 export-svc-cfg subcommand 225 eXtensible Access Control Markup Language. See  XACML external configuration store used, for single server configuration 47-49

[ 263 ]

F Failure URL attribute 141 federation 16, 17, 155 federation services 12 file based logging 236 FilesRepo plugin 187 filter parameter 215 flat file logging about 237 versus database logging 239 ForceAuth parameter 106 Forgerock URL 21

G Geronimo container 23 get-auth-cfg-entr command 108 get-auth-instance command 108 Glassfish container 22 Glassfish EE container 22 global services 72 Google apps about 177 OpenSSO, integrating with 177 SSO parameters, configuring 179, 180 gotoOnFail parameter 104 goto parameter 103, 104 group identities creating 219 deleting 221 groups managing, from command line tool 81 searching 216

H hosted identity provider configuring 171, 178 HOTP 121 HTTP basic authentication about 120

I IAM 7, 8 IBM WebSphere Application Server con-

tainer 23 identities agent identities, deleting 221 creating 161-163 deleting 221 group identities, deleting 221 searching 215 updating 220 user identities, deleting 221 Identity and Access Management. See  IAM identity attributes retrieving 217, 218 identity CRUD operations, OpenSSO about 215 agent identities, creating 218 group identities, creating 219 identities, searching 215 identity attributes, retrieving 217, 218 user identities, creating 219 identity repository scenarios 253-255 identity repository framework 185 identity repository plugins, OpenSSO about 186 AgentsRepo 187 AMSDKRepo 188 FilesRepo 187 LDAPv3Repo 187 SpecialRepo 187 identity stores about 27, 28 versus configuration store 24 identity stores, OpenSSO 192 IdRepo service 187 idRepoService.xml file 186 IDToken parameter 103 import-svc-cfg subcommand 227 inetuserstatus attribute 138 in-memory lockout about 141 considerations 141 installation, diagnostic tools 246 installation, OpenSSO server scenarios 249-251 iplanet-am-user-account-life attribute 138 iplanet-am-user-login-status attribute 138 iPSPCookie parameter 106 [ 264 ]

isTokenValid method invoking 212

J J2EE agents 158 JAAS 95, 111 Java application configuring 160 deploying 160 Java Authentication and Authorization Service. See  JAAS Java Cryptography Extension. See  JCE Java Database Connectivity. See  JDBC Java Key Store(JKS) 235 Java Security Server. See  JSS java.util.logging classes 235 JBOSS container 23 JCE 241 JDBC 120, 121 JSS 241

K Kerberos Distribution Center (KDC) 124 keystore creating 241, 242 keytool command 117, 171

L LDAP 115, 200 LDAP authentication about 108 authentication instance, creating 108 authentication instance, deleting 110 authentication instance, reading 109, 110 authentication instance, updating 109 authentication instance, using 110 ldapmodify tool 150 LDAP schema extending 87 LDAPv3Repo plugin 187 legacy SDK. See  Access manager repository plug-in level based authentication 100 Liberty Alliance Project URL 13

Lightweight Directory Access Protocol. See  LDAP list-auth-cfgs command 108 list-auth-instances command 108 Load balancer cookie 98 locale parameter 104, 105 log data base tables for OpenSSO 239 log events creating 213 Login Context Cookie 98 Login Failure Lockout Duration attribute 141 logname parameter 213 logout interface session, destroying 213 logstatus property 235

M MAC 241 Manifest Analysis and Certification. See  MAC max-psearch-count property 189 Membership module 120 message parameter 213 Microsoft Active Directory data store, creating for 199 Microsoft Active Directory Application Mode (ADAM) data store, creating for 199 Model-View-Controller. See  MVC module based authentication 99, 100 module parameter 187 multiple data store, configuring 204 multi server configuration, OpenSSO embedded configuration store used 50 prerequisites 51 verifying 55, 56 MVC 96

N notification about 189 persistent search based 189, 190 Time-To-Live (TTL) based 191 TTL based cache refresh 191

[ 265 ]

Download from Wow! eBook

authentication modules 114 authentication service 96, 97 authentication types 98, 99 authentication URL parameters 98-103 building, from source 28 command line tools, configuring 58-60 configuration change, performing 229 configuration data, backing up 224 configuration options 34-36 configuration store 24 configuring 31 configuring, command line configurator used 56, 57 configuring, on production server 230 configuring, with SSL/TLS 58 console customization 86 console landing page 69 console views 66-69 cookies 97 crash recovery 227, 228 custom authentication modules, adding 128 diagnostic tools 245 history 9 identity CRUD operations 215 identity repository plugins 186, 187, 188 identity stores 27, 28, 192 integrating, with Google apps 177 integrating, with Salesforce applications 170 log data base tables 239 logging 233 obtaining 28 overview 11 password reset application configuration 142 password reset service, configuring 143-148 policy 156 policy agents 156 policy service 156 privileges 66-69 problem solving, types 16-18 production environment, testing 229 realm 70 services 11-15 Session Service 129 support model 61

nsaccountlock attribute 138

O OASIS about 155 URL 13 OCSP 117 ODSEE about 197 data store, creating for 197, 198 ODSEE backup tools 227 One Time Password. See  OTP Online Certificate Status Protocol. See  OCSP On Premise 169 OpenAM about 10 versus OpenSSO 10 OpenDS about 25, 198 data store, creating for 198 opends directory 226 OpenDS password policy about 149 assigning, to user 150 creating 149 location of secret question 152, 153 password change after reset, forcing 150, 151 OpenLDAP about 200 data store, creating for 200 OpenLDAP data store creating 203 testing 203 OpenLDAP server configuring 200, 201 schema file, finding 201 OpenSSO about 137, 223 account lockout 138 adding, to existing deployment 52-54 administration interfaces 64 administrative console, accessing 65, 66 auditing 233 authentication chain 111 [ 266 ]

test configuration data, adapting 231 test server configuration, exporting 229, 230 troubleshooting issues 248 uninstalling 61 versus OpenAM 10 OpenSSOAgentBootstrap.properties file 162 OpenSSO audit logs 248 OpenSSO binary downloading 29, 30 OpenSSO configuration verifying 37, 38 OpenSSO configuration data backing up 226 OpenSSO configuration files backing up 225 OpenSSO, integrating with Google apps hosted identity provider, configuring 178 SSO, verifying 181, 182 user identities, provisioning 180 OpenSSO, integrating with Salesforce applications hosted identity provider, configuring 171 SSO, verifying 176, 177 user identities, provisioning 174, 175 OpenSSO Meta Data configuring, for Salesforce.com 172, 173, 174 OpenSSO Policy Service 77 OpenSSO product 22 OpenSSO server 245 OpenSSO services about 11 customizing 88 entitlements service 15 federation 12 Secure Token service 13, 14 web services security 13, 14 OpenSSO services, customizing about 88 attributes, adding to amUser.xml 88, 89 changes, testing 93, 94 custom attributes, adding to data store configurations 91 labels, adding 90 privileges, updating 92 updated user sevice schema, adding 90

user sevice schema, removing 89 OpenSSO web application deployment requisites 22 opensso.zip archive 245 OpenXDAS 232 Oracle Application Server container 22 Oracle DB 137 Oracle Directory Server Enterprise Edition. See  ODSEE Oracle WebLogic container 22 Organization for the Advancement of Structured Information Standards. See  OASIS OTP 121

P PAM 123 parameter 98 password change after reset forcing 150, 151 password reset scenarios 253-255 password reset application configuration about 142 prerequisites 142, 143 password reset service about 143 configuring, in OpenSSO 143-148 password reset service login assigning 143-148 service attributes, updating 143-148 PEP 15, 156 PersistAMCookie parameter 107 Persistent Session 99 physical lockout about 140 enabling 140 enforcing, in multi server environment 140 PKI 116 Pluggable Authentication Module. See  PAM Policy Administration Point(PAP) 156 policy agents about 156, 157 configuring 160 installing 160

[ 267 ]

types 157 Policy Decision Point (PDP) 156 Policy Enforcement Points. See  PEP policy, OpenSSO about 156 condition 156 creating 161-163 rule 156 subject 156 policy service 156, 157 policy store 157 prerequisites, REST 208 private REST interfaces 222 privileges 74-76 production server OpenSSO, configuring on 230 production system importing into 232 profile 71 Public Key Infrastructure. See  PKI pull model 191 push model 191 pwdreset attribute about 151 using 152

R RADIUS 122, 231 realm 66, 70 realm based authentication 101 recovery 223 register-auth-module command 108 Remote Authentication Dial-In User Service. See  RADIUS remote logging 240 representation 207 Representational State Transfer. See  REST resource 207 resource based authentication 102 REST about 207 history 207 prerequisites 208 REST interfaces invoking 210, 211 REST interfaces, invoking

about 210 authenticating, with URL parameters 211 authentication 210, 211 authorization 214 log events, creating 213 session, invalidating 213 SSO token, validating 212 REST-style architectures about 207 clients 207 servers 207 role based authentication 101 root realm 70 RSA SecurID 137 rule 156

S SaaS 169 SafeWord 122 Salesforce applications OpenSSO, integrating with 170 Salesforce.com OpenSSO Meta Data, configuring for 172, 173, 174 SAML 170 SAML 2.0 13 SAMLv2 response 176 sample application protecting, on Tomcat 158, 159 scenarios for agent configuration 255, 257 for authentication and session 252, 253 for command line tools 257, 258 for identity repository 253-255 for password reset 253-255 secure logging 240 Secure Token service 13, 14 SecurID 122 self service password reset 142 server configuration properties removing 85 updating 84, 85 server properties retrieving 84 service based authentication 100 Service Management Service(SMS) 235 [ 268 ]

Service Provider Interface. See  SPI Service Provider Interface plug-in. See  SPI plug-in ServletContext.getRealPath() method 250 session about 96 changes, notifying 134 constraints 135 invalidating 213 life cycle 131 persistence 135 polling 134 properties 133 state transition 132 structure 131 Session Failover 50 sessions managing. ssoadm tool used 86 Session Service about 129 schema 130 updating 130 Session tab 85 show-auth-modules command 108 single server configuration, OpenSSO embedded configuration store used 40-46 external configuration store used 47-49 Single Sign On. See  SSO software-as-a-service. See  SaaS source OpenSSO, building from 28 SpecialRepo plugin 187 SPI 95 SPI plug-in 185 SSL/TLS OpenSSO, configuring 58 SSO about 155 testing 164, 166 types 156 verifying 176-182 ssoadm tool about 64, 137-139, 226, 230 sessions, managing 86 ssoDiagnosticTools.zip 245 SSO parameters configuring, at Google apps 179, 180

SSO token about 212 user profile attributes, setting in 126, 127 validating 212 SSO Token Cookie 98 subject 156 subjectid parameter 213, 214 Subjects interface about 79, 80 sunAMAuthInvalidAttemptsData attribute 140 Sun Application Server container 22 Sun Identity Manager 65 Sun Java System Directory Server considering, as configuration store 26, 27

T test configuration data adapting 231 test server configuration exporting 229, 230 Tivoli DS data store, creating for 199 Tomcat sample application, protecting on 158, 159 trace level logging enabling 233, 234 troubleshooting 248 Trust Association Interceptor (TAI) 158 TTL context properties 191

U ums.xml file 188 Unix authentication module 123 unregister-auth-module command 108 update-auth-cfg-entr command 108 update-auth-instance command 108 uri parameter 214 URL parameters authenicating with 211 user OpenDS password policy, assigning to 150 user based authentication about 101 performing 113, 114 [ 269 ]

user identities creating 219 deleting 221 provisioning 174, 175, 180 searching for 216 user identity management 137 user profile attributes fetching 167, 168 setting up, in SSO token 126, 127 user profile requisites for core authentication module 124, 125 users managing, from command line tool 80 user schema 192

W WAR file 22 web agents 157 webapp directory 22 web services securing 17 web services security 13, 14 Windows Desktop SSO authentication module 124 Windows NT authentication module 123

X XACML 18

[ 270 ]

Thank you for buying

OpenAM

About Packt Publishing

Packt, pronounced 'packed', published its first book "Mastering phpMyAdmin for Effective MySQL Management" in April 2004 and subsequently continued to specialize in publishing highly focused books on specific technologies and solutions. Our books and publications share the experiences of your fellow IT professionals in adapting and customizing today's systems, applications, and frameworks. Our solution based books give you the knowledge and power to customize the software and technologies you're using to get the job done. Packt books are more specific and less general than the IT books you have seen in the past. Our unique business model allows us to bring you more focused information, giving you more of what you need to know, and less of what you don't. Packt is a modern, yet unique publishing company, which focuses on producing quality, cutting-edge books for communities of developers, administrators, and newbies alike. For more information, please visit our website: www.packtpub.com.

About Packt Open Source

In 2010, Packt launched two new brands, Packt Open Source and Packt Enterprise, in order to continue its focus on specialization. This book is part of the Packt Open Source brand, home to books published on software built around Open Source licences, and offering information to anybody from advanced developers to budding web designers. The Open Source brand also runs Packt's Open Source Royalty Scheme, by which Packt gives a royalty to each Open Source project about whose software a book is sold.

Writing for Packt

We welcome all inquiries from people who are interested in authoring. Book proposals should be sent to [email protected]. If your book idea is still at an early stage and you would like to discuss it first before writing a formal book proposal, contact us; one of our commissioning editors will get in touch with you. We're not just looking for published authors; if you have strong technical skills but no writing experience, our experienced editors can help you develop a writing career, or simply get some additional reward for your expertise.

Joomla! Web Security ISBN: 978-1-847194-88-6

Paperback: 264 pages

Secure your Joomla! website from common security threats with this easy-to-use guide 1.

Learn how to secure your Joomla! websites

2.

Real-world tools to protect against hacks on your site

3.

Implement disaster recovery features

4.

Set up SSL on your site

5.

Covers Joomla! 1.0 as well as 1.5

Pluggable Authentication Modules: The Definitive Guide to PAM for Linux SysAdmins and C Developers ISBN: 978-1-904811-32-9

Paperback: 124 pages

A comprehensive and practical guide to PAM for Linux: how modules work and how to implement them 1.

Understand and configure PAM

2.

Develop PAM-aware applications and your own PAMs using the API and C

3.

How to authenticate users in Active Directory, mount encrypted home directories, load SSH keys automatically, and restrict web and rsh services

Please check www.PacktPub.com for information on our titles

Download from Wow! eBook

Spring Security 3 ISBN: 978-1-847199-74-4

Paperback: 396 pages

Secure your web applications agains malicious intruders with this easy to folow practical guide 1.

Make your web applications impenetrable.

2.

Implement authentication and authorization of users.

3.

Integrate Spring Security 3 with common external security providers.

4.

Packed full with concrete, simple, and concise examples.

GlassFish Security ISBN: 978-1-847199-38-6

Paperback: 296 pages

Secure your GlassFish installation, Web applications, EJB applications, Application Client modules, and Web services 1.

Secure your GlassFish installation and J2EE applications

2.

Develop secure Java EE applications including Web, EJB, and Application Client modules

3.

Secure web services using GlassFish and OpenSSO web service security features

4.

Support SSL in GlassFish including Mutual Authentication and Certificate Realm with this practical guide

Please check www.PacktPub.com for information on our titles