Novell ACCESS MANAGER 3.1 SP1 - IDENTITY SERVER, Access Manager 3.1 SP1 User Manual

Identity Server Guide

Novell®

Access Manager

novdocx (en) 19 February 2010

AUTHORIZED DOCUMENTATION

3.1 SP1

March 17, 2010

www.novell.com

Novell Access Manager 3.1 SP1 Identity Server Guide

Legal Notices

Novell, Inc., makes no representations or warranties with respect to the contents or use of this documentation, and
specifically disclaims any express or implied warranties of merchantability or fitness for any particular purpose.
Further, Novell, Inc., reserves the right to revise this publication and to make changes to its content, at any time,
without obligation to notify any person or entity of such revisions or changes.

Further, Novell, Inc., makes no representations or warranties with respect to any software, and specifically disclaims
any express or implied warranties of merchantability or fitness for any particular purpose. Further, Novell, Inc.,
reserves the right to make changes to any and all parts of Novell software, at any time, without any obligation to
notify any person or entity of such changes.

Any products or technical information provided under this Agreement may be subject to U.S. export controls and the
trade laws of other countries. You agree to comply with all export control regulations and to obtain any required
licenses or classification to export, re-export or import deliverables. You agree not to export or re-export to entities on
the current U.S. export exclusion lists or to any embargoed or terrorist countries as specified in the U.S. export laws.
You agree to not use deliverables for prohibited nuclear, missile, or chemical biological weaponry end uses. See the

Novell International Trade Services Web page (http://www.novell.com/info/exports/) for more information on

exporting Novell software. Novell assumes no responsibility for your failure to obtain any necessary export
approvals.

novdocx (en) 19 February 2010

Copyright © 2006-2010 Novell, Inc. All rights reserved. No part of this publication may be reproduced, photocopied,
stored on a retrieval system, or transmitted without the express written consent of the publisher.

Novell, Inc.
404 Wyman Street, Suite 500
Waltham, MA 02451
U.S.A.
www.novell.com

Online Documentation: To access the latest online documentation for this and other Novell products, see

the Novell Documentation Web page (http://www.novell.com/documentation).

Novell Trademarks

For Novell trademarks, see the Novell Trademark and Service Mark list (http://www.novell.com/company/legal/

trademarks/tmlist.html).

Third-Party Materials

All third-party trademarks are the property of their respective owners.

novdocx (en) 19 February 2010

novdocx (en) 19 February 2010

4 Novell Access Manager 3.1 SP1 Identity Server Guide

Contents

About This Guide 11

1 Configuring an Identity Server 13

1.1 Managing a Cluster Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

1.1.1 Creating a Cluster Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

1.1.2 Assigning an Identity Server to a Cluster Configuration . . . . . . . . . . . . . . . . . . . . . . 19

1.1.3 Configuring Session Failover. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

1.1.4 Removing a Server from a Cluster Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

1.1.5 Managing a Cluster with Multiple Identity Servers . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

1.1.6 Enabling and Disabling Protocols . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

1.1.7 Modifying the Base URL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

1.2 Customizing Identity Server Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

1.2.1 Customizing Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

1.2.2 Customizing the Branding of the Error Page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

1.2.3 Customizing Tooltip Text for Authentication Contracts . . . . . . . . . . . . . . . . . . . . . . . 29

1.3 Customizing the Identity Server Login Page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

1.3.1 Selecting the Login Page and Modifying It . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

1.3.2 Configuring the Identity Server to Use Custom Login Pages . . . . . . . . . . . . . . . . . . 42

1.3.3 Troubleshooting Tips for Custom Login Pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47

1.4 Customizing the Identity Server Logout Page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48

1.4.1 Rebranding the Logout Page. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48

1.4.2 Replacing the Logout Page with a Custom Page . . . . . . . . . . . . . . . . . . . . . . . . . . . 48

1.5 Enabling Role-Based Access Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49

1.6 Using netHSM for the Signing Key Pair . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49

1.6.1 Understanding How Access Manager Uses Signing and Interacts with the netHSM

Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50

1.6.2 Configuring the Identity Server for netHSM. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52

1.7 Configuring Secure Communication on the Identity Server . . . . . . . . . . . . . . . . . . . . . . . . . . . 66

1.7.1 Viewing the Services That Use the Signing Key Pair . . . . . . . . . . . . . . . . . . . . . . . . 67

1.7.2 Viewing Services That Use the Encryption Key Pair . . . . . . . . . . . . . . . . . . . . . . . . . 68

1.7.3 Managing the Keys, Certificates, and Trust Stores . . . . . . . . . . . . . . . . . . . . . . . . . . 68

1.8 Security Considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71

1.8.1 Federation Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71

1.8.2 Authentication Contracts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72

1.8.3 Forcing 128-Bit Encryption . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72

novdocx (en) 19 February 2010

2 Configuring Local Authentication 75

2.1 Configuring Identity User Stores . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76

2.1.1 Using More Than One LDAP User Store. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76

2.1.2 Configuring the User Store . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77

2.1.3 Configuring an Admin User for the User Store . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80

2.1.4 Configuring a User Store for Secrets. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80

2.2 Creating Authentication Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88

2.2.1 Creating Basic or Form-Based Authentication Classes . . . . . . . . . . . . . . . . . . . . . . . 88

2.2.2 Specifying Common Class Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90

2.3 Configuring Authentication Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92

2.4 Configuring Authentication Contracts. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94

2.5 Using a Password Expiration Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96

2.5.1 URL Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97

Contents 5

2.5.2 Forcing Authentication after the Password Has Changed . . . . . . . . . . . . . . . . . . . . . 97

2.5.3 Grace Logins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98

2.5.4 Federated Accounts. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98

2.6 Specifying Authentication Defaults. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98

2.7 Managing Direct Access to the Identity Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99

2.7.1 Logging In to the User Portal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100

2.7.2 Specifying a Target . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101

2.7.3 Blocking Access to the WSDL Services Page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101

3 Configuring Advanced Local Authentication Procedures 105

3.1 Configuring for RADIUS Authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105

3.2 Configuring Mutual SSL (X.509) Authentication. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106

3.2.1 Setting Up Mutual SSL Authentication. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111

3.3 Creating an ORed Credential Class. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111

3.4 Configuring for Kerberos Authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113

3.4.1 Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114

3.4.2 Configuring Active Directory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115

3.4.3 Configuring the Identity Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117

3.4.4 Configuring the Clients . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123

3.4.5 Configuring the Access Gateway for Kerberos Authentication . . . . . . . . . . . . . . . . 124

3.4.6 Upgrading from Access Manager 3.0 SP4 or 3.1 . . . . . . . . . . . . . . . . . . . . . . . . . . 124

3.5 Configuring Access Manager for NESCM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125

3.5.1 Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125

3.5.2 Creating a User Store . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125

3.5.3 Creating a Contract for the Smart Card . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127

3.5.4 Assigning the NESCM Contract to a Protected Resource . . . . . . . . . . . . . . . . . . . . 131

3.5.5 Verifying the User’s Experience. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131

3.5.6 Troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132

novdocx (en) 19 February 2010

4 Defining Shared Settings 133

4.1 Configuring Attribute Sets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133

4.2 Editing Attribute Sets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135

4.3 Configuring User Matching Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136

4.4 Adding Custom Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137

4.4.1 Creating Shared Secret Names. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137

4.4.2 Creating LDAP Attribute Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138

4.5 Adding Authentication Card Images. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140

5 Configuring SAML and Liberty Trusted Providers 141

5.1 Understanding the Trust Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141

5.1.1 Identity Providers and Consumers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141

5.1.2 Embedded Service Providers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142

5.1.3 High-Level Steps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143

5.2 Configuring General Provider Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144

5.2.1 Configuring the General Identity Provider Options . . . . . . . . . . . . . . . . . . . . . . . . . 144

5.2.2 Configuring the General Identity Consumer Options . . . . . . . . . . . . . . . . . . . . . . . . 145

5.3 Creating a Trusted Provider . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145

5.4 Modifying a Trusted Provider . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148

5.4.1 Configuring Communication Security Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148

5.4.2 Using the Intersite Transfer Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150

5.4.3 Selecting Attributes for a Trusted Provider . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155

5.4.4 Managing Metadata . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156

5.4.5 Configuring an Authentication Request for an Identity Provider . . . . . . . . . . . . . . . 159

6 Novell Access Manager 3.1 SP1 Identity Server Guide

5.4.6 Configuring an Authentication Response for a Service Provider . . . . . . . . . . . . . . . 162

5.4.7 Managing the Authentication Card of an Identity Provider . . . . . . . . . . . . . . . . . . . 165

6 Configuring CardSpace 167

6.1 Overview of the CardSpace Authentication Process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167

6.2 Prerequisites for CardSpace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168

6.2.1 Enabling High Encryption . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169

6.2.2 Configuring the Client Machines for CardSpace . . . . . . . . . . . . . . . . . . . . . . . . . . . 169

6.3 Authenticating with a Personal Card . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171

6.4 Authenticating with a Managed Card . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174

6.4.1 Prerequisite . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174

6.4.2 Configuring a CardSpace Identity Provider . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174

6.4.3 Creating and Installing a Managed Card . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175

6.4.4 Configuring the Relying Party to Trust an Identity Provider. . . . . . . . . . . . . . . . . . . 176

6.4.5 Logging In with the Managed Card . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177

6.5 Authenticating with a Managed Card Backed by a Personal Card. . . . . . . . . . . . . . . . . . . . . 178

6.6 Configuring the Identity Server as a Relying Party . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179

6.6.1 Defining an Authentication Card and Profile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179

6.6.2 Defining a Trusted Provider . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181

6.6.3 Cleaning Up Identities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183

6.6.4 Defederating after User Portal Login . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183

6.7 Configuring the Identity Server as an Identity Provider . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183

6.7.1 Replacing the Signing Certificate. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183

6.7.2 Configuring STS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184

6.7.3 Creating a Managed Card Template . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185

6.8 Using CardSpace Cards for Authentication to Access Gateway Protected Resources . . . . . 186

novdocx (en) 19 February 2010

7 Configuring WS Federation 187

7.1 Using the Identity Server as an Identity Provider for ADFS . . . . . . . . . . . . . . . . . . . . . . . . . . 187

7.1.1 Configuring the Identity Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188

7.1.2 Configuring the ADFS Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193

7.1.3 Logging In . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195

7.1.4 Troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196

7.2 Using the ADFS Server as an Identity Provider for an Access Manager Protected Resource197

7.2.1 Configuring the Identity Server as a Service Provider . . . . . . . . . . . . . . . . . . . . . . . 198

7.2.2 Configuring the ADFS Server to Be an Identity Provider. . . . . . . . . . . . . . . . . . . . . 201

7.2.3 Logging In . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202

7.2.4 Additional WS Federation Configuration Options . . . . . . . . . . . . . . . . . . . . . . . . . . 203

7.3 Modifying a WS Federation Identity Provider . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203

7.3.1 Renaming the Identity Provider . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203

7.3.2 Configuring the Attributes Obtained at Authentication . . . . . . . . . . . . . . . . . . . . . . . 203

7.3.3 Modifying the User Identification Method. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204

7.3.4 Managing the Metadata . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205

7.3.5 Modifying the Authentication Card. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206

7.4 Modifying a WS Federation Service Provider. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206

7.4.1 Renaming the Service Provider . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206

7.4.2 Configuring the Attributes Sent with Authentication. . . . . . . . . . . . . . . . . . . . . . . . . 206

7.4.3 Modifying the Authentication Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207

7.4.4 Managing the Metadata . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208

8 Configuring User Identification Methods for Federation 209

8.1 Selecting a User Identification Method for Liberty or SAML 2.0. . . . . . . . . . . . . . . . . . . . . . . 209

8.2 Selecting a User Identification Method for SAML 1.1. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211

Contents 7

8.3 Configuring the Attribute Matching Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213

8.4 Defining the User Provisioning Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214

8.5 User Provisioning Error Messages. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217

9 Configuring Communication Profiles 219

9.1 Configuring a Liberty Profile. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219

9.2 Configuring a SAML 1.1 Profile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220

9.3 Configuring a SAML 2.0 Profile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220

10 Configuring Liberty Web Services 223

10.1 Configuring the Web Services Framework. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224

10.2 Enabling Web Services and Profiles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224

10.3 Editing Web Service Descriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225

10.4 Configuring Credential Profile Security and Display Settings. . . . . . . . . . . . . . . . . . . . . . . . . 226

10.5 Configuring Service and Profile Details . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228

10.6 Customizing Attribute Names. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231

10.7 Editing Web Service Policies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231

10.8 Configuring the Web Service Consumer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234

10.9 Mapping LDAP and Liberty Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235

10.9.1 Configuring One-to-One Attribute Maps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 236

10.9.2 Configuring Employee Type Attribute Maps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 238

10.9.3 Configuring Employee Status Attribute Maps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239

10.9.4 Configuring Postal Address Attribute Maps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240

10.9.5 Configuring Contact Method Attribute Maps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242

10.9.6 Configuring Gender Attribute Maps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243

10.9.7 Configuring Marital Status Attribute Maps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 244

novdocx (en) 19 February 2010

11 Maintaining an Identity Server 247

11.1 Managing an Identity Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247

11.1.1 Updating an Identity Server Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 248

11.1.2 Restarting the Identity Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249

11.2 Editing Server Details. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 250

11.3 Configuring Component Logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 250

11.3.1 Enabling Component Logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 250

11.3.2 Managing Log File Size . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252

11.4 Configuring Session-Based Logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 253

11.4.1 Creating the Administrator Class, Method, and Contract . . . . . . . . . . . . . . . . . . . . 253

11.4.2 Creating the Logging Session Class, Method, and Contract . . . . . . . . . . . . . . . . . . 255

11.4.3 Enabling Basic Logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256

11.4.4 Responding to an Incident . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256

11.5 Monitoring the Health of an Identity Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 259

11.5.1 Health States . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 259

11.5.2 Viewing the Health Details. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 259

11.6 Monitoring Identity Server Statistics. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262

11.6.1 Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 263

11.6.2 Authentications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 263

11.6.3 Incoming HTTP Requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 264

11.6.4 Outgoing HTTP Requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 265

11.6.5 Liberty . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 265

11.6.6 SAML 1.1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266

11.6.7 SAML 2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266

11.6.8 WSF (Web Services Framework) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266

8 Novell Access Manager 3.1 SP1 Identity Server Guide

11.6.9 Clustering. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268

11.6.10 LDAP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 269

11.7 Enabling Identity Server Audit Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 270

11.8 Monitoring Identity Server Alerts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 272

11.9 Viewing the Command Status of the Identity Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 272

12 Troubleshooting the Identity Server and Authentication 275

12.1 Useful Networking Tools for the Linux Identity Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 275

12.2 Troubleshooting 100101043 and 100101044 Liberty Metadata Load Errors. . . . . . . . . . . . . 275

12.2.1 The Metadata. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 276

12.2.2 DNS Name Resolution. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 277

12.2.3 Certificate Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 278

12.2.4 Certificates in the Required Trust Stores . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 279

12.2.5 Certificates in the Correct Certificate Store . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 280

12.2.6 Enabling Debug Logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 281

12.2.7 Testing Whether the Provider Can Access the Metadata . . . . . . . . . . . . . . . . . . . . 283

12.2.8 Manually Creating Any Auto-Generated Certificates . . . . . . . . . . . . . . . . . . . . . . . 283

12.3 Authentication Issues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283

12.3.1 Authentication Classes and Duplicate Common Names . . . . . . . . . . . . . . . . . . . . . 284

12.3.2 General Authentication Troubleshooting Tips . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 284

12.3.3 Slow Authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285

12.3.4 Basic Authentication Fails with an eDirectory User Store . . . . . . . . . . . . . . . . . . . . 285

12.3.5 Federation Errors. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285

12.3.6 Mutual Authentication Troubleshooting Tips . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285

12.3.7 Browser Hangs in an Authentication Redirect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 286

12.4 Translating the Identity Server Configuration Port . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 286

12.4.1 A Simple Redirect Script . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 287

12.4.2 Configuring iptables for Multiple Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 289

12.5 Problems Reading Keystores after Identity Server Re-installation. . . . . . . . . . . . . . . . . . . . . 291

novdocx (en) 19 February 2010

A Sample Custom Login Pages 293

A.1 Modified login.jsp File for Credential Prompts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 293

A.2 Custom nidp.jsp File with Custom Credentials. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 296

A.2.1 The Modified nidp.jsp File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 296

A.2.2 The Modified main.jsp File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 302

A.2.3 The Method and the Contract . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 303

A.3 Custom 3.1 login.jsp File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 303

A.3.1 The Modified login.jsp File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 303

A.3.2 The Method and the Contract . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 306

A.4 Custom 3.0 login.jsp File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 306

A.4.1 Modifying the File. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 307

A.4.2 The Method and the Contract . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 310

B About Liberty 311

C Understanding How Access Manager Uses SAML 313

C.1 Attribute Mapping with Liberty . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 313

C.2 Trusted Provider Reference Metadata . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 314

C.3 Identity Federation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 314

C.4 Authorization Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 314

C.5 What's New in SAML 2.0? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 314

C.6 Identity Provider Process Flow. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 315

Contents 9

C.7 SAML Service Provider Process Flow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 316

D Data Model Extension XML 319

D.1 Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 319

D.2 Writing Data Model Extension XML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 322

novdocx (en) 19 February 2010

10 Novell Access Manager 3.1 SP1 Identity Server Guide

About This Guide

This guide describes the following features of the Access Manager Identity Server:

 Chapter 1, “Configuring an Identity Server,” on page 13

 Chapter 2, “Configuring Local Authentication,” on page 75

 Chapter 3, “Configuring Advanced Local Authentication Procedures,” on page 105

 Chapter 4, “Defining Shared Settings,” on page 133

 Chapter 5, “Configuring SAML and Liberty Trusted Providers,” on page 141

 Chapter 6, “Configuring CardSpace,” on page 167

 Chapter 7, “Configuring WS Federation,” on page 187

 Chapter 8, “Configuring User Identification Methods for Federation,” on page 209

 Chapter 9, “Configuring Communication Profiles,” on page 219

 Chapter 10, “Configuring Liberty Web Services,” on page 223

 Chapter 11, “Maintaining an Identity Server,” on page 247

novdocx (en) 19 February 2010

 Chapter 12, “Troubleshooting the Identity Server and Authentication,” on page 275

This guide is intended to help you understand and configure all of the features provided by the
Identity Server, and includes advanced topics.

It is recommended that you first become familiar with the information in the Novell Access Manager

3.1 SP1 Setup Guide, which helps you understand how to perform a basic Identity Server

configuration, set up a resource protected by an Access Gateway, and configure SSL.

The setup guide and this guide are designed to work together, and important information and setup
steps are not always repeated in both places.

Audience

This guide is intended for Access Manager administrators. It is assumed that you have knowledge of
evolving Internet protocols, such as:

 Extensible Markup Language (XML)

 Simple Object Access Protocol (SOAP)

 Security Assertion Markup Language (SAML)

 Public Key Infrastructure (PKI) digital signature concepts and Internet security

 Secure Socket Layer/Transport Layer Security (SSL/TSL)

 Hypertext Transfer Protocol (HTTP and HTTPS)

 Uniform Resource Identifiers (URIs)

 Domain Name System (DNS)

 Web Services Description Language (WSDL)

About This Guide 11

Feedback

We want to hear your comments and suggestions about this guide and the other documentation
included with this product. Please use the User Comments feature at the bottom of each page of the
online documentation, or go to Documentation Feedback (http://www.novell.com/documentation/

feedback.html) at www.novell.com/documentation/feedback.html and enter your comments there.

Documentation Updates

For the most recent version of the Access Manager Identity Server Guide, visit the Novell Access

Manager Documentation Web site (http://www.novell.com/documentation/novellaccessmanager31/
).

Additional Documentation

Before proceeding, you should be familiar with the Novell Access Manager 3.1 SP1 Installation

Guide and the Novell Access Manager 3.1 SP1 Setup Guide, which provides information about

setting up the Access Manager system.

If you are unfamiliar with SAML 1.1, see “SAML Overview” (http://www.novell.com/

documentation/saml/saml/data/ag8qdk7.html) on the Documentation Web site (http://
www.novell.com/documentation/a-z.html).

novdocx (en) 19 February 2010

For conceptual information about Liberty, and to learn about what is new for SAML 2.0, see

Appendix B, “About Liberty,” on page 311 and Appendix C, “Understanding How Access Manager
Uses SAML,” on page 313.

For information about the other Access Manager devices and features, see the following:

 Novell Access Manager 3.1 SP1 Administration Console Guide

 Novell Access Manager 3.1 SP1 Access Gateway Guide

 Novell Access Manager 3.1 SP1 Policy Management Guide

 Novell Access Manager 3.1 SP1 Agent Guide

 Novell Access Manager 3.1 SP1 SSL VPN Server Guide

 Novell Access Manager 3.1 SP1 Event Codes

Documentation Conventions

In Novell documentation, a greater-than symbol (>) is used to separate actions within a step and
items in a cross-reference path.

A trademark symbol (®, TM, etc.) denotes a Novell trademark. An asterisk (*) denotes a third-party
trademark.

When a single pathname can be written with a backslash for some platforms or a forward slash for
other platforms, the pathname is presented with a backslash. Users of platforms that require a
forward slash, such as Linux* or UNIX*, should use forward slashes as required by your software.

12 Novell Access Manager 3.1 SP1 Identity Server Guide

1

Configuring an Identity Server

After you log in to the Administration Console, click Devices > Identity Servers. The system
displays the newly installed server.

A newly installed Identity Server is in an unconfigured state and is halted. It remains in this state and
cannot function until you create an Identity Server configuration and assign the Identity Server to
the new configuration. The configuration defines how the Identity Server functions in an Access
Manager configuration. In an Identity Server cluster, multiple servers use the same configuration
and provide failover and load balancing services.

novdocx (en) 19 February 2010

1

 Section 1.1, “Managing a Cluster Configuration,” on page 13

 Section 1.2, “Customizing Identity Server Messages,” on page 25

 Section 1.3, “Customizing the Identity Server Login Page,” on page 30

 Section 1.4, “Customizing the Identity Server Logout Page,” on page 48

 Section 1.5, “Enabling Role-Based Access Control,” on page 49

 Section 1.6, “Using netHSM for the Signing Key Pair,” on page 49

 Section 1.7, “Configuring Secure Communication on the Identity Server,” on page 66

 Section 1.8, “Security Considerations,” on page 71

For information on configuring local authentication options, see the following:

 Chapter 2, “Configuring Local Authentication,” on page 75

 Chapter 3, “Configuring Advanced Local Authentication Procedures,” on page 105

 Chapter 4, “Defining Shared Settings,” on page 133

 Chapter 10, “Configuring Liberty Web Services,” on page 223

1.1 Managing a Cluster Configuration

After you install an Identity Server, you must create a cluster configuration in order to configure the
Identity Server. Even if you have only one Identity Server, you must assign it to a cluster
configuration to configure it. If you have multiple Identity Servers, you can create multiple
configurations and assign different Identity Servers to them as shown in Figure 1-1.

Configuring an Identity Server

13

Figure 1-1 Identity Server Configurations

novdocx (en) 19 February 2010

Configuration A

Identity Server 1

Identity Server 2

Configuration A Configuration B

Identity Server 1

Identity Server 2

When you assign multiple Identity Servers to the same configuration, you need to install a load
balancer that supports either Layer 4 or Layer 7. This device is referred to as an L4 switch in this
manual. The L4 switch allows the work load to be balanced among the machines.

Whether you have one machine or multiple machines in a cluster, the Access Manager software
configuration process is the same. This section describes the following cluster management tasks:

 Section 1.1.1, “Creating a Cluster Configuration,” on page 14

 Section 1.1.2, “Assigning an Identity Server to a Cluster Configuration,” on page 19

 Section 1.1.3, “Configuring Session Failover,” on page 19

 Section 1.1.4, “Removing a Server from a Cluster Configuration,” on page 20

 Section 1.1.5, “Managing a Cluster with Multiple Identity Servers,” on page 21

 Section 1.1.6, “Enabling and Disabling Protocols,” on page 24

 Section 1.1.7, “Modifying the Base URL,” on page 24

1.1.1 Creating a Cluster Configuration

This section discusses the settings available for an Identity Server configuration, such as importing
SSL certificates, enabling introductions, and configuring identity consumer settings. You should be
familiar with “Creating a Basic Identity Server Configuration” in the Novell Access Manager 3.1

SP1 Setup Guide before proceeding.

An Identity Server always operates as an identity provider and can optionally be configured to run as
an identity consumer (also known as a service provider), using Liberty, SAML 1.1, SAML 2.0,
CardSpace or WS Federation protocols. In an Identity Server cluster, multiple servers use the same
configuration.

In an Identity Server configuration, you specify the following information:

 The base URL for the server or clustered server site.

 Certificates for the Identity Server, identity provider, and identity consumer.

 Authentication settings, such as whether the identity provider requires signed authentications

from service providers.

 The service domains used for publishing and discovering authentications.

14 Novell Access Manager 3.1 SP1 Identity Server Guide

 Organizational and contact information for the server, which is published in the metadata of the

Liberty and SAML protocols.

 The LDAP directories (user stores) used to authenticate users, and the trusted root for secure

communication between the Identity Server and the user store.

To create an Identity Server configuration:

1 In the Administration Console, click Devices > Identity Servers.

2 Select the Identity Server’s check box, then click New Cluster.

Selecting the server is one way to assign it to the cluster configuration.

3 In the New Cluster dialog box, specify a name for the cluster configuration.

If you did not select the server in the previous step, you can now select the server or servers that
you want to assign to this configuration.

For more information about assigning servers to a configuration, see Section 1.1.2, “Assigning

an Identity Server to a Cluster Configuration,” on page 19.

4 Click OK.

novdocx (en) 19 February 2010

5 Fill in the following fields to specify the Base URL for your Identity Server configuration:

Configuring an Identity Server 15

Name: Specify a name by which you want to refer to the configuration. This field is populated
with the name you provided in the New Cluster dialog box. You can change this name here, if
necessary.

IMPORTANT: Carefully determine your settings for the base URL, protocol, and domain.
After you have configured trust relationships between providers, changing these settings
invalidates the trust model and requires a reimport of the provider’s metadata.

Modifying the base URL also invalidates the trust between the Embedded Service Provider of
Access Manager devices. To re-establish the trust after modifying the base URL, you must
restart the Embedded Service Provider on each device.

Base URL: Specify the application path for the Identity Server. The Identity Server protocols
rely on this base URL to generate URL endpoints for each protocol.

 Protocol: Select the communication protocol. Specify HTTPS in order to run securely (in

SSL mode) and for provisioning. Use HTTP only if you do not require security.

 Domain: Specify the DNS name assigned to the Identity Server. When you are using an

L4 switch, this DNS name should resolve to the virtual IP address set up on the L4 switch
for the Identity Servers. Using an IP address is not recommended.

 Port: Specify the port value for the protocol. Default ports are 8080 for HTTP or 8443 for

HTTPS. If you want to use port 80 or 433, specify the port here.

novdocx (en) 19 February 2010

 If you are configuring a Linux Identity Server, you must also configure the operating

system to translate the port. See Section 12.4, “Translating the Identity Server

Configuration Port,” on page 286.

 If you are configuring a Windows Identity Server, you must also modify the Tomcat

server.xml

file located in the

\Program Files\Novell\Tomcat\conf

directory.

Change the ports from 8080 and 8443 to 80 and 443, then restart the Tomcat service.

 Application: Specify the Identity Server application. Leave the default value nidp.

SSL Certificate: Displays the currently assigned SSL certificate.

The Identity Server comes with a test-connector certificate that you must replace to use SSL in
your production environment. You can replace the test certificate now or after you configure
the Identity Server. If you create the certificate and replace the test-connector now, you can
save some time by restarting Tomcat only once. Tomcat must be restarted whenever you assign
an Identity Server to a configuration and whenever you update a certificate key store. See

Section 1.7.3, “Managing the Keys, Certificates, and Trust Stores,” on page 68.

For information on how to replace the test-connector certificate, see “Enabling SSL

Communication” in the Novell Access Manager 3.1 SP1 Setup Guide.

6 To configure session limits, fill in the following fields:

LDAP Access: Specify the maximum number of LDAP connections the Identity Server can
create to access the configuration store. You can adjust this amount for system performance.

Session Timeout: Specify the session inactivity time allowed before timing out. This is a
global setting that applies to any resource that authenticates to this Identity Server or Identity
Server cluster. The default setting is 60 minutes.

16 Novell Access Manager 3.1 SP1 Identity Server Guide

This is a security setting:

 Lower it if you want idle sessions to time out with a smaller window of opportunity for

someone to take over a session of a user who takes a break, leaving an active session
unattended.

 Increase it if you want to allow idle users to have a longer time period before they are

forced to log in again.

If the resource is configured to use Basic authentication, the session times out, but the browser
must be closed to terminate the session.

Limit User Sessions: Specify whether user sessions are limited. If selected, you can specify
the maximum number of concurrent sessions a user is allowed to authenticate.

If you decide to limit user sessions, you should also give close consideration to the session
timeout value (the default is 60 minutes). If the user closes the browser without logging out (or
an error causes the browser to close), the session is not cleared until the session timeout
expires. If the user session limit is reached and those sessions have not been cleared with a
logout, the user cannot log in again until the session timeout expires for one of the sessions.

When enabled, this option affects performance in a cluster with multiple Identity Servers.
When a user is limited to a specific number of sessions, the Identity Servers must check with
the other servers before establishing a new session.

novdocx (en) 19 February 2010

Allow multiple browser session logout: Specify whether a user with more than one session to
the server is presented with an option to log out of all sessions. If you do not select this option,
only the current session can be logged out. Deselect this option in instances where multiple
users log in as guests. Then, when one user logs out, none of the other guests are logged out.

When you enable this option, you must also restart any Embedded Service Providers that use
this Identity Server configuration.

7 To configure TCP timeouts, fill in the following fields:

LDAP: Specify how long an LDAP request to the user store can take before timing out.

Proxy: Specify how long a request to another cluster member can take before timing out.

When a member of a cluster receives a request from a user who has authenticated with another
cluster member, the member sends a request to the authenticating member for information
about the user.

Request: Specify how long an HTTP request to another device can take before timing out.

8 To control which protocols can be used for authentication, select one or more of the following

protocols:

Liberty: Uses a structured version of SAML to exchange authentication and authorization data
between trusted identity providers and service providers and provides the framework for user
federation.

IMPORTANT: If you are using other Access Manager devices such as the Access Gateway,
SSL VPN, or the J2EE Agents, you need to enable the Liberty protocol. The Access Manager
devices use an Embedded Service Provider. If you disable the Liberty protocol, you disable the
trusted relationships these devices have with the Identity Server, and authentication fails.

SAML 1.1: Uses XML for exchanging authentication and authorization data between trusted
identity providers and service providers.

SAML 2.0: Uses XML for exchanging encrypted authentication and authorization data
between trusted identity providers and service providers and provides the framework for user
federation.

Configuring an Identity Server 17

STS: A security token service that creates digital identities from claims, which can then be
used as a card or a token for authentication.

CardSpace: Uses Microsoft* client software that stores a user’s information in a digital
identity or information card, which can then be presented and used as authentication
credentials.

WS Federation: Allows disparate security mechanisms to exchange information about
identities, attributes, and authentication.

9 To continue creating the Identity Server configuration, click Next.

The system displays the Organization page.

novdocx (en) 19 February 2010

Use this page to specify organization information for the Identity Server configuration. The
information you specify on this page is published in the metadata for the Liberty 1.2 and
SAML protocols. The metadata is traded with federation partners and supplies various
information regarding contact and organization information located at the Identity Server.

The following fields require information:

 Name: The name of the organization.

 Display Name: The display name for the organization.

 URL: The organization’s URL for contact purposes.

Optional fields include Company, First Name, Last Name, Email, Telephone, and Contact
Type .

10 Click Next to configure the user store.

You must reference your own user store and auto-import the SSL certificate. See Section 2.1.2,

“Configuring the User Store,” on page 77 for information about this procedure.

18 Novell Access Manager 3.1 SP1 Identity Server Guide

11 After you configure the user store, the system displays the new configuration on the Servers

page.

The status icons for the configuration and the Identity Server should turn green. It might take several
seconds for the Identity Server to start and for the system to display a green light. If it does not, it is
likely that the Identity Server is not communicating with the user store you set up. Ensure that you
have entered the user store information correctly, and that you imported the SSL certificate to the
user store. (Edit > Local > [User Store Name].)

1.1.2 Assigning an Identity Server to a Cluster Configuration

novdocx (en) 19 February 2010

After you create a configuration, you must assign an Identity Server to it. For clustering, you can
assign more than one Identity Server to the configuration (see Section 1.1.5, “Managing a Cluster

with Multiple Identity Servers,” on page 21 for the steps to set up a cluster). A configuration uses

any shared settings you have specified, such as attribute sets, user matching expressions, and custom
attributes that are defined for the server.

1 In the Administration Console, click Devices > Identity Servers.

2 On the Servers page, select the server’s check box, then choose Actions > Assign to Cluster.

You can select all displayed servers by selecting the top-level Server check box.

3 Select the configuration’s check box, then click Assign.

You are prompted to restart Tomcat. The status icon for the Identity Server should turn green. It
might take several seconds for the Identity Server to start and for the system to display the
green light.

1.1.3 Configuring Session Failover

When you set up an Identity Server cluster and add more than one Identity Server to the cluster, you
have set up fault tolerance. This ensures that if one of the Identity Servers goes down, users still
have access to your site because the remaining Identity Server can be used for authentication.
However, it doesn’t provide session failover. If a user has authenticated to the failed Identity Server,
that user is prompted to authenticate and the session information is lost.

When you enable session failover and an Identity Server goes down, the user’s session information
is preserved. Another peer server in the cluster re-creates the authoritative session information in the
background. The user is not required to log in again and experiences no interruption of services.

 “Prerequisites” on page 20

 “Configuring Session Failover” on page 20

 “How Fallover Peers Are Selected” on page 20

Configuring an Identity Server 19

Prerequisites

 An Identity Server cluster with two or more Identity Servers.

 Sufficient memory on the Identity Servers to store additional authentication information. When

an Identity Server is selected to be a failover peer, the Identity Server stores about 1 K of
session information for each user authenticated on the other machine.

 Sufficient network bandwidth for the increased login traffic. The Identity Server sends the

session information to all the Identity Servers that have been selected to be its failover peers.

 All trusted Embedded Services Providers need to be configured to send the attributes used in

Form Fill and Identity Injection policies at authentication. If you use any attributes other than
the standard credential attributes in your contracts, you need to send these attributes also. To
configure the attributes to send, click Devices > Identity Servers > Edit > Liberty > [Name of
Service Provider] > Attributes.

Configuring Session Failover

1 In the Administration Console, click Devices > Identity Servers.

novdocx (en) 19 February 2010

2 In the list of clusters and Identity Servers, click the name of an Identity Server cluster.

3 Click the IDP Failover Peer Server Count, then select the number of failover peers you want

each Identity Server to have.

 To disable this feature, select 0.

 To enable this feature, select one or two less than the number of servers in your cluster.

For example, if you have 4 servers in your clusters and you want to allow for one server
being down for maintenance, select 3 (4-1=3). If you want to allow for the possibility of
having two down, select 2 (4-2=2).

If you have eight or more servers in your cluster, the formula 8-2=6 gives each server 6
peers. This is probably more peers than you need for session failover. In a larger cluster,
you should probably limit the number of peers to 2 or 3. If you select too many peers, your
machines might require more memory to hold the session data and you might slow down
your network with the additional traffic for session information.

4 Click OK.

How Fallover Peers Are Selected

The failover peers for an Identity Server are selected according to their proximity. Access Manager
sorts the members of the cluster by their IP addresses and ranks them according to how close their IP
addresses are to the server who needs to be assigned failover peers. It selects the closest peers for the
assignment. For example, if a cluster member exists on the same subnet, that member is selected to
be a failover peer before a peer that exist on a different subnet.

1.1.4 Removing a Server from a Cluster Configuration

Removing an Identity Server from a configuration disassociates the Identity Server from the cluster
configuration. The configuration, however, remains intact and can be reassigned later or assigned to
another server.

1 In the Administration Console, click Devices > Identity Servers.

20 Novell Access Manager 3.1 SP1 Identity Server Guide

2 Select the server, then click Stop. Wait for the Health indicator to turn red.

3 Select the server, then choose Actions > Remove from Cluster.

For information about deleting an Identity Server, see Section 11.1, “Managing an Identity Server,”

on page 247.

1.1.5 Managing a Cluster with Multiple Identity Servers

To add capacity and to enable system failover, you can cluster a group of Identity Servers and
configure them in a cluster configuration to act as a single server. However, a cluster is not intended
for login failover because all authentication data for a user is stored in memory on the cluster
member or authenticating server that originally handled the user's authentication. If this server
malfunctions, all users whose authentication data resides on the authenticating server must
reauthenticate unless you also configure session failover (see Section 1.1.3, “Configuring Session

Failover,” on page 19).

All requests that require user authentication information must be processed on the user’s
authenticating server. For example, if an HTTP request is received by a cluster server other than the
authenticating server, then the HTTP request is forwarded to the authenticating server in the cluster.
This server processes the HTTP request and routes it back through the forwarding cluster member
and then to the original requester.

novdocx (en) 19 February 2010

A cluster of Identity Servers should reside behind an L4 switch. Clients access the virtual IP (VIP)
address of the cluster presented on the L4 switch, and the L4 switch alleviates server load by
balancing traffic across the cluster. Whenever a user accesses the virtual IP address assigned to the
L4 switch, the system routes the user to one of the Identity Servers in the cluster, as traffic
necessitates.

 “Prerequisites” on page 21

 “Setup” on page 22

Prerequisites

 An L4 switch installed. You can use the same switch for Identity Server clustering and Access

Gateway clustering, provided that you use different virtual IPs. The LB algorithm can be
anything (hash/sticky bit), defined at the Real server level. For configuration tips, see
“Configuration Tips for the L4 Switch ” in the Novell Access Manager 3.1 SP1 Setup Guide.

 Persistence (sticky) sessions enabled on the L4 switch. Normally you define this at the virtual

server level.

 An Identity Server configuration created for the cluster. You assign all the Identity Servers to

this configuration. See Section 1.1.1, “Creating a Cluster Configuration,” on page 14 for
information about creating an Identity Server configuration. See Section 1.1.2, “Assigning an

Identity Server to a Cluster Configuration,” on page 19 for information about assigning identity

servers to configurations.

The base URL DNS name of this configuration must resolve via DNS to the IP address of the
L4 virtual IP address. The L4 switch balances the load between the Identity Servers in the
cluster.

 Ensure that the L4 administration server using port 8080 has the following TCP ports open:

 8443 (secure Administration Console)

Configuring an Identity Server 21

 7801 + 1 (for back-channel communication with cluster members. You need to open two

consecutive ports such as 7801 and 7802.)

 636 (for secure LDAP)

 389 (for clear LDAP)

 524 (network control protocol on the L4 switch for server communication)

The identity provider ports must also be open:

 8080 (non-secure login)

 8443 (secure login)

 1443 (server communication)

If you are using introductions (see Section 1.1.1, “Creating a Cluster Configuration,” on

page 14), you must configure the L4 switch to load balance on ports 8445 (identity provider)

and 8446 (identity consumer).

Setup

1 Install the additional Identity Servers.

novdocx (en) 19 February 2010

During installation, choose option 2, Install Novell Identity Server. You run the installation for
each new Identity Server you want to add. Specify the IP address and administration credentials
of each additional Identity Server. If you are installing on a machine without the Administration
Console, the installation asks you for the Administration Console’s IP address. After you install
the Identity Servers, the servers are displayed on the Servers page in Identity Servers.

2 Assign the Identity Servers to the same cluster configuration (see Section 1.1.2, “Assigning an

Identity Server to a Cluster Configuration,” on page 19).

3 Click the name of the cluster configuration.

22 Novell Access Manager 3.1 SP1 Identity Server Guide

The system displays the Cluster Details page, which lets you manage the configuration’s
cluster details, health, alerts, and statistics.

4 Click Edit.

5 Fill in the following fields as required:

novdocx (en) 19 February 2010

Cluster Communication Backchannel: Specify a communications channel over which the
cluster members maintain the integrity of the cluster. For example, this TCP channel is used to
detect new cluster members as they join the cluster, and to detect members that leave the
cluster. A small percentage of this TCP traffic is used to help cluster members determine which
cluster member would best handle a given request. This back channel should not be confused
with the IP address/port over which cluster members provide proxy requests to peer cluster
members.

 Port: Specify the TCP port of the cluster back channel on all of the Identity Servers in the

cluster. 7801 is the default TCP port.

Because the cluster back channel uses TCP, you can have cluster members on different
networks. However, firewalls must allow the ports specified here plus one to pass through.
You need to open two ports for each cluster, for example, 7801 and 7802.

 Encrypt: Encrypts the content of the messages that are sent between cluster members.

Level Four Switch Port Translation: Configure the L4 switch to translate the port of the
incoming request to a new port when the request is sent to a cluster member. Because the
cluster members communicate with each other over the same IP address/port as the L4 switch,
the cluster implementation needs to know what that port is. The translated port is the port on
the cluster members where other cluster members can contact it. This is the IP address and port
where cluster members provide proxy requests to other cluster members.

 Port translation is enabled on switch: Specify whether the port of the L4 switch is

different from the port of the cluster member. For example, enable this option when the L4
switch is using port 443 and the Identity Server is using port 8443.

 Cluster member translated port: Specify the port of the cluster member.

IDP Failover Peer Server Count: For configuration information, see Section 1.1.3,

“Configuring Session Failover,” on page 19.

6 Click OK, then update the Identity Server as prompted.

Configuring an Identity Server 23

1.1.6 Enabling and Disabling Protocols

You can control which protocols can be used for authenticating with an Identity Server
configuration. A protocol must be enabled and configured before users can use the protocol for
authentication. For tight security, consider disabling the protocols that you are not going to use for
authentication.

When disabling a protocol, updating the Identity Server configuration is not enough. You must stop
and start the Identity Server.

1 In the Administration Console, click Devices > Identity Servers > Edit.

2 In the Enabled Protocols section, select the protocols to enable

3 To disable a protocol, deselect it.

4 Click OK.

5 (Conditional) If you have enabled a protocol, update the Identity Server.

6 (Conditional) If you have disabled a protocol, updating the Identity Server is not enough.

6a Select the Identity Server, then click Stop.

6b When the health turns red, select the Identity Server, then click Start.

novdocx (en) 19 February 2010

6c Repeat the process for each Identity Server in the cluster.

1.1.7 Modifying the Base URL

When configuring an Identity Server, you must carefully determine your settings for the base URL,
protocol, and domain. Changing the base URL invalidates the trust model and requires a reimport of
the provider’s metadata, and a restart of the affected Embedded Service Providers. It also changes
the ID of the provider and the URLs that others use for access.

When you change the base URL of the Identity Server, you invalidate the following trusted
relationships:

 The trusted relationships that the Identity Server has established with each Access Manager

device that has been configured to use the Identity Server for authentication

 The trusted relationship that each Access Manager device has established with the Identity

Server when the Identity Server configuration was selected.

 The trusted relationships that the Identity Server has established with other service providers.

The sessions of any logged in users are destroyed and no user can log in and access protected
resources until the trust relationships are reestablished.

To modify the base URL and re-establish trust relationships:

1 In the Administration Console, click Devices > Identity Servers > Edit.

2 Change the protocol, domain, port, and application settings, as necessary.

3 Click OK.

4 On the Identity Servers page, click Update.

This re-creates the trusted Identity Server configuration to use the new Base URL and
metadata.

24 Novell Access Manager 3.1 SP1 Identity Server Guide

5 Restart Tomcat on each Identity Server in the configuration:

 Linux Identity Server: Enter the following command:

/etc/init.d/novell-tomcat5 restart

 Windows Identity Server: Enter the following commands:

net stop Tomcat5
net start Tomcat5

6 For each Access Manager device configured to trust the configuration of this modified base

URL, you must update the device so that the Embedded Service Provider trusts the new
Identity Server configuration:

 Click Access Gateways, then click Update for any servers with a Status of Update.

 Click SSL VPNs, then click Update for any servers with a Status of Update.

 Click J2EE Agents, then click Update for any agents with a Status of Update.

7 For each service provider you have configured to trust the configuration of this modified base

URL, you must send them the new metadata and have them re-import it.

For information about setting up SSL and changing an Identity Server from HTTP to HTTPS, see
“Enabling SSL Communication” in the Novell Access Manager 3.1 SP1 Setup Guide.

novdocx (en) 19 February 2010

1.2 Customizing Identity Server Messages

 Section 1.2.1, “Customizing Messages,” on page 25

 Section 1.2.2, “Customizing the Branding of the Error Page,” on page 27

 Section 1.2.3, “Customizing Tooltip Text for Authentication Contracts,” on page 29

1.2.1 Customizing Messages

1 To customize the error pages, determine whether you need one custom file or multiple files:

 If you do not need to support multiple languages, you can create one custom file for all

your customized messages.

 If you need to support multiple languages, you need to create a custom file for each

language you want to customize.

2 Create the custom properties file and name it:

To support one language, name the file

To support multiple languages, create a

nidp_custom_resources.properties

nidp_custom_resources.<le_cy>.properties

file for each supported language. Replace <le_cy> with the standard convention for Java
Resource Bundles for the language or the language and country. For example:

nidp_custom_resources_en_US.properties
nidp_custom_resources_fr.properties
nidp_custom_resources_es.properties

If you want to support a custom messages for a language and a country and for just the
language, you must create two files. For example:

nidp_custom_resources_es_VE.properties
nidp_custom_resources_es.properties

3 Copy the

nidp.jar

file to a working area. This file is located in the following directory:

.

Configuring an Identity Server 25

novdocx (en) 19 February 2010

Linux:

Windows:

4 Unzipthe

5 In the working directory, locate the

com/novell/nidp/resource/strings
com/novell/nidp/resource/logging
com/novell/nidp/resource/jsp
com/novell/nidp/resource/jcc
com/novell/nidp/resource/noxlate
com/novell/nidp/liberty/wsf/idsis/ppservice/model
com/novell/nidp/liberty/wsf/idsis/epservice/model
com/novell/nidp/liberty/wsf/idsis/opservice/model
com/novell/nidp/liberty/wsf/idsis/apservice/model
com/novell/nidp/liberty/wsf/interaction
com/novell/nidp/liberty/wsf/idsis/ssservice/model
com/novell/nidp/servlets/handler/identityeditor
com/novell/nidp/servlets/handler/identityaccesseditor
com/novell/nidp/liberty/wsf/idsis/model
com/novell/nidp/liberty/wsf/idsis/authority/ldap/attribute/plugins/
resources
com/novell/nidp/liberty/wsf/idsis/ldapservice/model

/var/opt/novell/tomcat5/webapps/nidp/WEB-INF/lib

C:\Program Files\Novell\Tomcat\webapps\nidp\WEB-INF\lib

nidp.jar

file to the working directory.

.properties

files in the following directories:

The properties files that have been localized contain the messages that end users might see. The
properties files that have not been localized contain messages that the end users should not see.

6 Locate the messages you want to customize and copy them to your custom file.

All the messages you want to customize are placed in this file, even though they come from
different properties files. Your file should look similar to the following if you selected to
customize messages from the

SSModelResources_en_US.properties

NIDPMAIN.100=An Identity Provider response was received that failed to
authenticate this session.
NIDPMAIN.101=A request for identity federation could not be completed.
NIDPMAIN.102=A request for identity federation termination could not be
completed.

SS.WKSLdapCreds = LDAP Credentials
SS.WKSELdapCredsUserName = LDAP User Name
SS.WKSELdapCredsUserDN = LDAP User DN
SS.WKSELdapCredsUserPassword = LDAP Password
SS.WKSX509Creds = X509 Credentials

nidp_resources_en_US.properties

file. For example:

file and the

7 (Conditional) If you are supporting multiple languages, copy the messages to each custom

language file.

8 Replace the messages in the file with your custom messages.

Replace the string after the equals (=) sign with your translated or customized message.

If you are using double-byte characters, the characters need to be in Unicode, hexadecimal
format with a

prefix. For example:

\u5c71

.

\u

9 Save the file.

10 Copy the custom properties file to the following directory on all Identity Servers in the cluster:

Linux:

Windows:

/var/opt/novell/tomcat5/webapps/nidp/WEB-INF/classes

C:\Program Files\Novell\Tomcat\webapps\nidp\WEB-INF\classes

26 Novell Access Manager 3.1 SP1 Identity Server Guide

11 (Optional) To enable messages about the loading of the custom properties files, enable debug

logging:

11a In the Administration Console, click Devices > Identity Servers > Edit > Logging.

11b In the Component File Logger Levels section, select Debug level for Application.

11c Click OK, then update the Identity Server.

12 Restart Tomcat.

 Linux Identity Server: Enter the following command:

/etc/init.d/novell-tomcat5 restart

 Windows Identity Server: Enter the following commands:

net stop Tomcat5

net start Tomcat5

13 (Optional) To verify the loading of the custom properties files:

13a View the log file by clicking Auditing > General Logging.

13b Search for messages similar to the following in the

The named Custom Properties File was loaded and will be used:

catalina.out or stdout.log

file:

novdocx (en) 19 February 2010

Custom Properties File successfully loaded! Name: <Custom Properties
FileName>

An error occurred loading a specific Custom Properties File. Loading
of other Custom Properties Files will continue.

<Error Description>, Attempting to load Custom Properties File! Name:
<Custom Properties FileName>

The locale specifier in the Custom Properties File filename could not
be successfully parsed into a valid locale. Loading of other Custom
Properties Files will continue.

Custom Properties File load failed. Could not determine correct
locale! Name: <Custom Properties FileName>

A general error occurred loading Custom Properties Files. Loading will
stop and all un-loaded Custom Properties Files will not be loaded.

<Error Description>, Attempting to load Custom Properties Files!

To create custom error pages for the Access Gateway, see “Customizing Error Pages on the Gateway

Appliance” in the Novell Access Manager 3.1 SP1 Access Gateway Guide.

1.2.2 Customizing the Branding of the Error Page

The following page (

err.jsp

) is returned when the Identity Server encounters an error:

Configuring an Identity Server 27

The file is located in the following directory.

novdocx (en) 19 February 2010

Linux:

Windows:

/var/opt/novell/tomcat5/webapps/nidp/jsp

\Program Files\Novell\Tomcat\webapps\nidp\jsp

IMPORTANT: After you have customized this page, you need to ensure you back up this page
before doing an upgrade. The upgrade process overrides any custom changes made to the

err.jsp

page.

For information on customizing the error message, see Section 1.2.1, “Customizing Messages,” on

page 25.

You can customize the following items:

 The window title and the display title. See “Customizing the Titles” on page 28.

 The header image and the Novell logo. See “Customizing the Images” on page 29.

 Background colors. See “Customizing the Colors” on page 29.

Customizing the Titles

The window title appears in the browser title bar. To replace this text, open the
locate the following text that appears between the

<title><%=handler.getResource(JSPResDesc.TITLE)%></title>

Replace the content between the

<title>

and

<head></head>

</title>

tags with the title you want to appear. For

tags:

err.jsp

file and

example:

<title>My Company</title>

The display title is the title that appears in the top frame of the page. Locate the following text that
appears in the

<div id="title"><%=handler.getResource(JSPResDesc.PRODUCT)%></div>

<body>

of the page:

Replace the content between the
For example:

28 Novell Access Manager 3.1 SP1 Identity Server Guide

<div id="title">

and

</div>

with the title you want to appear.

<div id="title">My Company</div>

Customizing the Images

novdocx (en) 19 February 2010

To replace the header image, open the

err.jsp

file and locate the following text in the body of the

file.

<div><img src="/nesp/images/AccessMan_Login_Head.png"></div>

Replace the value of the

src

attribute with the path and filename of the image you want to use.

To replace the Novell logo image, locate the following text in the body of the file.

<div id="logo"><img src="/nesp/images/AccessMan31_Nlogo.png"></div>

Replace the value of the

src

attribute with the path and filename of the image you want to use.

Customizing the Colors

To change the background colors on the page, modify the color values in the

<head>

.

<style>

section of the

1.2.3 Customizing Tooltip Text for Authentication Contracts

The strings that users see when they mouse over the cards for authentication contracts can be
customized. If you need to support only one language, modify the text in the Administration
Console.

1 In the Administration Console, click Devices > Identity Servers > Edit > Local > Contracts.

2 Click the name of a contract, then click Authentication Card.

3 Replace the English text in the Tex t option with the required language, then click OK.

4 Repeat Step 2 and Step 3 for each contract in the list.

5 Click OK, then update the Identity Server.

If you need to support multiple languages, you need to localize the tooltips. The nidsCardText
attribute of the nidsAuthLocalContract object needs to be changed to a resource ID. The following
procedure explains how to do this in the Administration Console. You can also use an LDAP
browser.

1 In the Administration Console, click Devices > Identity Servers > Edit > Local > Contracts.

2 Click the name of a contract, then click Authentication Card.

3 Replace the text in the Tex t option with a resource ID.

For example, replace

Name/Password - Form

with

CUSTOM_NamePwdFormToolTip

.

4 Click OK.

5 Repeat Step 2 through Step 4 for each contract in the list.

6 Click OK, then update the Identity Server.

7 Use custom string resource files to define the localized strings.

7a Change to the

WEB-INF/classes

directory.

7b For each supported language, create a properties file. For example:

Configuring an Identity Server 29

nidp_custom_resources_fr.properties
nidp_custom_resources_es.properties

If you have already created these files for custom messages (see Section 1.2.1,

“Customizing Messages,” on page 25), use the existing files.

7c For each resource ID you have created, add an entry that contains the resource ID and the

text you want displayed for that language. For example:

CUSTOM_NamePwdFormToolTip=Forma de Nombre/Clave

7d Repeat Step 7c for each supported language file.

8 Restart Tomcat.

 Linux Identity Server: Enter the following command:

/etc/init.d/novell-tomcat5 restart

 Windows Identity Server: Enter the following commands:

net stop Tomcat5
net start Tomcat5

1.3 Customizing the Identity Server Login Page

novdocx (en) 19 February 2010

You can create custom login pages that are displayed when the user authenticates to the Identity
Server. You might want to rebrand the User Portal or authenticate users with non-default attributes
(such as the email address attribute rather than the cn attribute). You also might be fronting several
protected resources with an Access Gateway, and you need to create a unique login page for each
resource.

When you customize the login page, you need to decide on the type of page to use. See

Section 1.3.1, “Selecting the Login Page and Modifying It,” on page 31. After you have made that

decision, you need to configure the Identity Server to display the correct login page. See

Section 1.3.2, “Configuring the Identity Server to Use Custom Login Pages,” on page 42.

Using Custom Pages from Previous Releases: The process for customizing login pages has been
modified in Access Manager 3.1 SP1. This new process requires some modifications to login pages
that have been customized for either 3.1 or 3.0. If you need information on these modification
procedures, see the following sections in the Novell Access Manager 3.1 SP1 Installation Guide:

 “Modifying 3.0 Login Pages for 3.1 SP1”

 “Upgrading from Access Manager 3.1 to 3.1 SP1”

Modifying the Target of the User Portal: If you want to control the target when users log directly
into the Identity Server, see Section 2.7.2, “Specifying a Target,” on page 101.

Modifying Error Pages: Both the Identity Server and the Access Gateway return error pages to the
user. For information on customizing these messages and pages, see the following:

 “Customizing Identity Server Messages” on page 25

 “Customizing Error Pages on the Gateway Appliance” in the Novell Access Manager 3.1 SP1

Access Gateway Guide

30 Novell Access Manager 3.1 SP1 Identity Server Guide

1.3.1 Selecting the Login Page and Modifying It

You must be familiar with customizing JSP files to create a customized login page. You can use any
of the following methods to produce the page:

 If you only need to customize the credentials (for example prompt the user for an email address

rather than a name), you can make most of the modifications in the Administration Console.
You need to add some properties to a method, create a contract from that method, and modify
the prompt in the

login.jsp

Default Login Page to Prompt for Different Credentials” on page 31.

 If you want to maintain the features of the 3.1 page and use its authentication cards but you

want to remove the Novell branding, you need to modify the
uses iframes, so the devices that your users use for authentication must also support iframes.
For configuration information, see “Customizing the nidp.jsp File” on page 33.

 If you don’t need the authentication cards and if the devices that your users use for

authentication support iframes, you can start with the
configuration information, see “Modifying the 3.1 login.jsp File” on page 38.

 If some of your users are using devices that don’t support iframes, you need to customize the

3.0 login page. For configuration information, see “Modifying the 3.0 Login Page” on page 38.

file. For configuration information, see “Customizing the

nidp.jsp

login.jsp

file. The

nidp.jsp

file and customize it. For

file

novdocx (en) 19 February 2010

IMPORTANT: After you have created customized login pages, you need to ensure that you back
them up before doing an upgrade. The upgrade process overrides any custom changes made to JSP
files that use the same filename as those included with the product.

During an upgrade, you can select to restore custom login pages, but Novell still recommends that
you have your own backup of any customized files.

Customizing the Default Login Page to Prompt for Different Credentials

This section explains how to prompt the users for an identifier other than the user’s name. Figure 1-

2 displays the default login page with the username prompt.

Figure 1-2 Modifying the Credential Prompts

login.jsp

Configuring an Identity Server 31

novdocx (en) 19 February 2010

This section explains how to modify the content of the

login.jsp

file. If you want to modify other

aspects of this page, you need to select one of the other methods.

The instructions below explain how to create a method that sets up the appropriate query so that the
user can be found in the user store with an identifier other than the username (the cn attribute). The
instructions then explain how to create a contract that uses this method and how to modify the

login.jsp

page so that it prompts for the appropriate identifier such as an email address instead of

a username.

1 Create a method with the appropriate query:

1a In the Administration Console, click Devices > Identity Servers > Edit > Local > Methods.

1b Click New, then specify a Display Name.

1c In the drop-down menu for classes, select a class that is a username/password class.

1d Leave the Identifies User option enabled, and configure the user store option according to

your needs.

1e In the Properties section, click New, then specify the following values:

Property Name:

Property Value:

Query

(objectclass=person)(mail=%Ecom_User_ID%)

This property is defined so that it queries the user store for the attribute you want to use
rather than the cn attribute (in this case, the mail attribute of the person class). The

%Ecom_User_ID%

%EMail_Address%

this to

variable is the default variable name on the login page. You can change

if you also change the value in your custom login page.

For more information on how to use this property, see “Query Property” on page 90.

1f In the Properties section, click New, then specify the following values:

Property Name:

Property Value:

Replace <filename> with the name of the custom

JSP

<filename>

login.jsp

so that the page prompts the user for an e-mail address rather than a username. This must
be the filename without the JSP extension. For example, if you name your file

email_login.jsp

, then you would specify

email_login

for the property value.

1g Click OK.

2 Create a contract that uses this method.

2a Click Contracts > New.

2b Select the method you just created.

2c Configure the other options to fit your requirements.

For information on configuring the other options for a contract, see Section 2.4,

“Configuring Authentication Contracts,” on page 94.

2d Click OK.

3 Update the Identity Server.

4 Copy the

login.jsp

file and rename it. The JSP files are located on the Identity Server in the

following directory:

Linux:

/var/opt/novell/tomcat5/webapps/nidp/jsp

page you are going to create

Windows:

32 Novell Access Manager 3.1 SP1 Identity Server Guide

C:\Program Files\Novell\Tomcat\webapps\nidp\jsp

novdocx (en) 19 February 2010

5 (Conditional) If you modified the

%Ecom_User_ID%

variable, find the string in the file and

replace it with your variable.

6 (Conditional) If you need to support only one language, modify the prompt in the

login.jsp

file:

6a Find the following string in the file:

<label><%=handler.getResource(JSPResDesc.USERNAME)%></label>

6b Replace it with the string you want, for example:

<label>Email Address:</label>

6c Copy the modified file to each Identity Server in the cluster.

6d Back up your customized file.

7 (Conditional) If you need to localize the prompt for multiple languages, create a custom

message properties file for the login prompt. (For more information on how to create a custom
message properties file, see Section 1.2.1, “Customizing Messages,” on page 25.)

The following steps assume you want to change the username prompt to an e-mail address
prompt.

7a Find the following definition in the

unzipped

JSP.50=Username:

nidp.jar

file.

com/novell/nidp/resource/jsp

directory of the

7b Add this definition to your custom properties file and modify it so that it prompts the user

for an e-mail address.

JSP.50=Email Address:

7c Translate the value and add this entry to your localized custom properties files.

7d Copy the customized properties files to the

WEB-INF/classes

directory of each Identity

Server in the cluster.

7e Restart Tomcat on each Identity Server.

Linux Identity Server: Enter the following command:

/etc/init.d/novell-tomcat5 restart

Windows Identity Server: Enter the following commands:

net stop Tomcat5
net start Tomcat5

8 To view a sample custom page with these modifications, see Section A.1, “Modified login.jsp

File for Credential Prompts,” on page 293.

Customizing the nidp.jsp File

Figure 1-3 displays the default login page provided by Access Manager. Multiple JSPs are used to

create the page.

Configuring an Identity Server 33

Figure 1-3 The JSPs that Create the Login Page

nidp.jsp

menus.jsp

login.jsp

content.jsp

novdocx (en) 19 February 2010

You can use the
name and the Novell logo. The

login.jsp

nidp.jsp

file to customize the header with the Novell Access Manager product

menus.jsp

file controls the Authentication and User Login tabs. The

file controls the credential frame with username and password. The

content.jsp

controls what is displayed on the page, including the available authentication cards.

The following sections explain how to modify the

 “Rebranding the Header” on page 34

 “Customizing the Card Display” on page 36

 “Customizing the Credential Frame” on page 36

nidp.jsp

file.

Rebranding the Header

1 Copy the

nidp.jsp

file and rename it. The JSP files are located on the Identity Server in the

following directory:

Linux:

Windows:

/var/opt/novell/tomcat5/webapps/nidp/jsp

C:\Program Files\Novell\Tomcat\webapps\nidp\jsp

2 Replace the header title that appears in the top frame (“Novell Access Manager” in Figure 1-3):

2a Locate the following string at the top of the file.

String hdrTitle = handler.getResource(JSPResDesc.PRODUCT);

2b Replace the value with the title you want to appear. For example:

String hdrTitle = "My Company"

Make sure to enclose your title value with double quotes.

3 Replace the window title that appears in the browser title bar:

3a Locate the following line that appears between the

<title><%=handler.getResource(JSPResDesc.TITLE)%></title>

3b Replace the content between the

<title>

and

<head></head>

</title>

tags with the title you want to

tags:

appear. For example:

<title>My Company</title>

file

34 Novell Access Manager 3.1 SP1 Identity Server Guide

4 Replace the Access Manager logo on the left of the header (see Figure 1-3):

4a Locate the following string:

String hdrImage = "AMHeader_image.png";

4b Replace the value in the quotes with the path and the filename of the image you want to

use.

For example, if you created a

hdrImage

String hdrImage = "/custom_images/myapp.png"

string would have a value similar to the following:

/custom_images

directory in the

images

directory, the

5 Replace the Novell logo on the right of the header (see Figure 1-3):

5a Locate the following string:

String hdrLogo = "AMHeader_logo.png";

5b Replace the value of the

hdrLogo

string with the path and the filename of the image you

want to use.

For example, if you created a

hdrLogo

String hdrLogo = "/custom_images/companylogo.png"

string would have a value similar to the following:

/custom

_images directory in the

images

directory, the

6 To change the background image for the header (which allows for variable sizing of the page):

6a Locate the following string:

String hdrBgndImg = "AMHeader_background.png";

6b Replace the value of the

hdrBgndImg

string with the path and the filename of the image
you want to use. You can use a color or an image that can be repeated. The style is set to
repeat it from left to right as the window expands.

For example, if you created a

hdrBgndImg

String hdrBgndImg = "/custom_images/mybackground.png"

string would have a value similar to the following:

/custom_images

directory in the

images

directory, the

7 If your custom images or title do not appear in the header where you want them, you need to

modify the style section.

novdocx (en) 19 February 2010

7a Locate the following lines:

#header { background-image: url(<%=
handler.getImage(hdrBgndImg,false)%>); background-repeat: repeat-x; }

#logo { position: absolute; top: 0px; right: 0px; }

#title { position: absolute; font-size: 1.2em; color: white; top:
13px; left: 55px; }

7b Modify the top, left, and right values.

8 To change the background colors on the page, modify the color values in the

of the

<head>

element.

<style>

section

9 If you need to create multiple custom login pages, repeat Step 1 through Step 8.

10 Copy the custom login pages and the images they require to each Identity Server in the cluster.

11 Continue with one of the following tasks:

 To modify what appears in the credential frame, continue with “Customizing the

Credential Frame” on page 36.

Configuring an Identity Server 35

 To control the cards displayed in the Authentication Cards section, see “Customizing the

Card Display” on page 36.

 To configure the Identity Server to use your custom pages, see “Adding Logic to the

main.jsp File” on page 43.

 To view a sample custom page with these modifications, see Section A.2, “Custom

nidp.jsp File with Custom Credentials,” on page 296.

Customizing the Card Display

The easiest method to control what appears in the Authentication Cards section is not by modifying

content.jsp

the

file. It is by using the Show Card option that appears on the definition of each
card. If this option is not selected, the card does not appear in the Authentication Cards section. Each
contract has an associated card. For information on modifying the card options, see Section 2.4,

“Configuring Authentication Contracts,” on page 94.

Continue with one of the following:

 To modify what appears in the credential frame, continue with “Customizing the Credential

Frame” on page 36

 To configure the Identity Server to use your custom pages, see “Adding Logic to the main.jsp

File” on page 43.

novdocx (en) 19 February 2010

Customizing the Credential Frame

The most common reason for modifying the

login.jsp

page is to prompt the users for an identifier
other than the user’s name. To do this, you need to create a method that sets up the appropriate query
so that the user can be found in the user store with an identifier other than the username. You then
need to create a contract that uses this method. You also need to modify the prompt in the

login.jsp

page to match the identifier you are prompting for.

1 Create a method with the appropriate query:

1a In the Administration Console, click Devices > Identity Servers > Edit > Local > Methods.

1b Click New, then specify a Display Name.

1c In the drop-down menu for classes, select a class that is a username/password class.

1d Leave the Identifies User option enabled, and configure the user store option according to

your needs.

1e In the Properties section, click New, then specify the following values:

Property Name:

Property Value:

Query

(objectclass=person)(mail=%Ecom_User_ID%)

This property is defined so that it queries the user store for the attribute you want to use
rather than the cn attribute (in this case, the mail attribute of the person class). Change
mail to the name of the attribute in your user store that you want to use for the user
identifier.

%Ecom_User_ID%

The
change this to something like
custom login page.

For more information on how to use this property, see “Query Property” on page 90.

1f In the Properties section, click New, then specify the following values:

36 Novell Access Manager 3.1 SP1 Identity Server Guide

variable is the default variable name on the login page. You can

%EMail_Address%

if you also change the value in your

novdocx (en) 19 February 2010

Property Name:

Property Value:

JSP

<filename>

Replace <filename> with the name of the custom
so that the page prompts the user for an e-mail address rather than a username. This must
be the filename without the JSP extension. For example, if you name your file

email_login.jsp

, then you would specify

1g Click OK.

2 Create a contract that uses this method:

2a Click Contracts > New.

2b Select the method you just created.

2c Configure the other options to fit your requirements.

If you are creating multiple custom login pages with customized credentials, you might
want to use the URI to hint at which custom

nidp.jsp

followed by the name of the custom

login1/custom1
login2/custom2
login3/custom3

file. For example, the following URI values have the filename of the login page

nidp.jsp

For information on configuring the other options for a contract, see Section 2.4,

“Configuring Authentication Contracts,” on page 94.

2d Update the Identity Server.

login.jsp

email_login

login.jsp

file is used with which custom

page:

page you are going to create

for the property value.

3 Copy the

login.jsp

file and rename it. The JSP files are located on the Identity Server in the

following directory:

Linux:

Windows:

4 (Conditional) If you modified the

/var/opt/novell/tomcat5/webapps/nidp/jsp

C:\Program Files\Novell\Tomcat\webapps\nidp\jsp

%Ecom_User_ID%

variable, find the string in the file and

replace it with your variable.

5 (Conditional) If you need to support only one language, modify the prompt in the

login.jsp

file:

5a Find the following string in the file:

<label><%=handler.getResource(JSPResDesc.USERNAME)%></label>

5b Replace it with the string you want, for example:

<label>Email Address:</label>

5c Copy the modified file to each Identity Server in the cluster.

5d Back up your customized file.

6 (Conditional) If you need to localize the prompt for multiple languages, create a custom

message properties file for the login prompt. (For more information on how to create a custom
message properties file, see Section 1.2.1, “Customizing Messages,” on page 25.)

The following steps assume you want to change the username prompt to an e-mail address
prompt.

6a Find the following definition in the

unzipped

JSP.50=Username:

nidp.jar

file.

com/novell/nidp/resource/jsp

directory of the

Configuring an Identity Server 37

6b Add this definition to your custom properties file and modify it so that it prompts the user

for an e-mail address.

JSP.50=Email Address:

6c Translate the value and add this entry to your localized custom properties files.

novdocx (en) 19 February 2010

6d Copy the customized properties files to the

WEB-INF/classes

directory of each Identity

Server in the cluster.

6e Restart Tomcat on each Identity Server.

Linux Identity Server: Enter the following command:

/etc/init.d/novell-tomcat5 restart

Windows Identity Server: Enter the following commands:

net stop Tomcat5
net start Tomcat5

7 To view a sample custom page with these modifications, see Section A.2, “Custom nidp.jsp

File with Custom Credentials,” on page 296.

8 To specify which customized

main.jsp

file. Continue with “Adding Logic to the main.jsp File” on page 43.

nidp.jsp

to display with the contract, you must modify the

Modifying the 3.1 login.jsp File

The

login.jsp

file gives you just the credential frame with the login prompts in an iframe. It has no
branding header. If you use this page, you are responsible for writing the HTML code for the header
and the branding.

1 Copy the

login.jsp

file and rename it. The JSP files are located on the Identity Server in the

following directory:

Linux:

Windows:

/var/opt/novell/tomcat5/webapps/nidp/jsp

C:\Program Files\Novell\Tomcat\webapps\nidp\jsp

2 Add the custom branding and any other content you require to the file.

3 To modify the credentials, see “Customizing the Credential Frame” on page 36.

4 Repeat Step 1 through Step 3 for each resource that requires unique branding.

5 Copy the files to each Identity Server in the cluster.

6 Back up your customized files.

7 (Optional) To view a sample custom page with these modifications, see Section A.3, “Custom

3.1 login.jsp File,” on page 303.

8 Continue with “Using Properties to Specify the Login Page” on page 42.

Modifying the 3.0 Login Page

If you need a login page that doesn’t use iframes, you can use the 3.0 login page as the starting file
for your custom login page. Figure 1-4 illustrates the default look and feel of this page.

38 Novell Access Manager 3.1 SP1 Identity Server Guide

Figure 1-4 Access Manager 3.0 Default Login Page

You can change the Novell branding and modify the credential prompts.

 “Modifying the Branding in the 3.0 Login Page” on page 39

 “Modifying the Credentials in the 3.0 Login Page” on page 40

Modifying the Branding in the 3.0 Login Page

novdocx (en) 19 February 2010

1 Copy the

/var/opt/novell/tomcat4/webapps/nidp/jsp/login.jsp

file from your 3.0

Identity Server and rename it.

If you do not have a 3.0

login.jsp

file, copy the modified version of this file from

“Modifications Required for a 3.0 Login Page” in the Novell Access Manager 3.1 SP1

Installation Guide to a true text editor. Delete all the extra line breaks.

2 (Conditional) If you are using the file from your 3.0 Identity Server, modify it so that it can

compile on a 3.1 Identity Server. For instructions, see “Modifications Required for a 3.0 Login

Page” in the Novell Access Manager 3.1 SP1 Installation Guide.

3 Replace the “Access Manager 3.0 Login” string.

3a Find the following line in the file:

<div id="title"><b><%=handler.getResource(JSPResDesc.TITLE)%></b></
div>

3b Replace

<%=handler.getResource(JSPResDesc.TITLE)%>

with your string. Your line

should look similar to the following:

<div id="title"><b>HHB Partner</b></div>

4 Replace the “Local Login” string.

When a 3.0 page runs on a 3.1 system, the “Local Login” string is replaced by the product
string, “Novell Access Manager”. To modify this string:

4a Locate the following string in the file.

<div id="locallabel"><b><%=handler.getResource(JSPResDesc.PRODUCT)%></
b></div>

4b Replace

<%=handler.getResource(JSPResDesc.PRODUCT)%>

with the title you want

to appear. For example:

<div id="locallabel"><b>My Company</b></div>

5 Replace the window title that appears in the browser title bar:

5a Find the following lines in the file:

Configuring an Identity Server 39

<META HTTP-EQUIV="Content-Language" CONTENT="<%=handler.getLanguage
Code()%>">
<title><%=handler.getResource(JSPResDesc.TITLE)%></title>

5b Replace the content between the

<title>

and

</title>

tags with the title you want to

appear. For example:

<title>My World</title>

6 Remove the Novell N logo:

6a Find the following line in the file:.

<div id="headimage"><img src="<%= request.getContextPath() %>/images/
Odyssey_LoginHead.gif" alt="" height="80" width="550" border="0"></
div>

6b Replace

Odyssey_LoginHead.gif

with

Odyssey_Head.gif

.

6c Save the file.

7 Select one of the following tasks:

 To modify what appears in the credential frame, continue with “Modifying the Credentials

in the 3.0 Login Page” on page 40.

 To view a file with these modifications, see Section A.4, “Custom 3.0 login.jsp File,” on

page 306.

novdocx (en) 19 February 2010

 To configure the Identity Server to use your custom pages, see “Using Properties to

Specify the Login Page” on page 42.

Modifying the Credentials in the 3.0 Login Page

1 Create a method with the appropriate query:

1a In the Administration Console, click Devices > Identity Servers > Edit > Local > Methods.

1b Click New, then specify a Display Name.

1c In the drop-down menu for classes, select a class that is a username/password class.

1d Leave the Identifies User option enabled, and configure the user store option according to

your needs.

1e In the Properties section, click New, then specify the following values:

Property Name:

Property Value:

Query

(objectclass=person)(mail=%Ecom_User_ID%)

This property is defined so that it queries the user store for the attribute you want to use
rather than the cn attribute (in this case the mail attribute of the person class). The

%Ecom_User_ID%

%EMail_Address%

this to

variable is the default variable name on the login page. You can change

as long as you also change the value in your custom login page.

For more information on how to use this property, see “Query Property” on page 90.

1f Click OK.

1g Create a contract that uses this method.

For information on configuring a contract, see Section 2.4, “Configuring Authentication

Contracts,” on page 94.

1h Update the Identity Server.

40 Novell Access Manager 3.1 SP1 Identity Server Guide

2 (Conditional) If you need to support only one language, modify the string in your custom login

file:

2a Find the following string in the file:

<label style="width: 100px"><%=handler.getResource(JSPResDesc.
USERNAME)%></label>

2b Replace it with the string you want, for example:

<label style="width: 100px">Email Address:</label>

2c Copy the modified file to each Identity Server in the cluster.

2d Update the Identity Server cluster.

2e Back up your customized file.

3 (Conditional) If you need to localize the prompt for multiple languages, create a custom

message properties file for the login prompt. (For more information on how to create a custom
message properties file, see Section 1.2.1, “Customizing Messages,” on page 25.)

The following steps assume you want to change the Username prompt to an Email Address
prompt.

novdocx (en) 19 February 2010

3a Find the following definition in the

unzipped

JSP.50=Username:

nidp.jar

file.

com/novell/nidp/resource/jsp

directory of the

3b Add this definition to your custom properties file and modify it so that it prompts the user

for an e-mail address.

JSP.50=Email Address:

3c Translate the value and add this entry to your localized custom properties files.

3d Copy the customized properties files to the

WEB-INF/classes

directory of each Identity

Server in the cluster.

3e Copy the custom login page to the JSP directory of each Identity Server in the cluster.

3f Restart Tomcat on each Identity Server.

Linux Identity Server: Enter the following command:

/etc/init.d/novell-tomcat5 restart

Windows Identity Server: Enter the following commands:

net stop Tomcat5
net start Tomcat5

4 (Optional) To view a customized 3.0 login page, see Section A.4, “Custom 3.0 login.jsp File,”

on page 306.

5 Continue with “Using Properties to Specify the Login Page” on page 42.

Configuring an Identity Server 41

1.3.2 Configuring the Identity Server to Use Custom Login
Pages

There are two ways to configure the Identity Server to use a custom login page. You can use
properties or you can modify the
modifications.

main.jsp

file. Which method you can use depends upon your

novdocx (en) 19 February 2010

 You can use properties if you created your custom page from the 3.1

login.jsp

page or have
modified a 3.0 custom page to work on 3.1. See “Using Properties to Specify the Login Page”

on page 42.

 If you created your custom page from the

the main custom page for authentication. You must modify the

nidp.jsp

file, you cannot use properties to specify

main.jsp

file. See “Adding

Logic to the main.jsp File” on page 43.

Using Properties to Specify the Login Page

For each resource that needs a unique login page, you need to create an authentication method and
add the JSP and MainJSP properties to the method. You then need to create a contract for each
method.

The following steps assume that the custom login page is called

custom1.jsp

.

1 Create a method for a custom login page:

1a In the Administration Console, click Devices > Identity Servers > Edit > Local > Methods.

1b Select one of the following actions:

 If you have create a method for a Query property to be used with your custom login

page, click the name of the method.

 If you didn’t modify the credentials on the login page, click New, specify a display

name, select a password class, and configure a user store.

1c In the Properties section, click New, then specify the following.

Property Name: MainJSP

Property Value: true

This property indicates that you want to use a custom login page with this method. It also
indicates that the custom login page contains the prompts for user credentials.

Property names and values are case sensitive.

1d Click OK.

1e (Conditional) If the Properties section does not contain a JSP property, click New, specify

the following, then click OK.

Property Name: JSP

Property Value: custom1

The property value for the JSP property is the name of the custom login file without the

JSP

extension. Replace

custom1

with the name of your custom login file. This property

determines which login page is displayed when this method is used. The filename cannot

nidp

contain

42 Novell Access Manager 3.1 SP1 Identity Server Guide

as part of its name.

For more information about setting property values, see Section 2.2.2, “Specifying

Common Class Properties,” on page 90.

1f (Conditional) If you created multiple custom login pages, repeat Step 1b through Step 1e

for each page.

2 For each method that you modified for a custom login page, create a contract:

2a Click Contracts, then click New.

2b Fill in the fields to fit the needs of the resource, but make sure to assign the custom

method as the method for the contract.

2c Click Next, configure a card for the contract, then click Finish.

3 Update the Identity Server.

4 For each resource that you have created a custom login page, assign that resource to use the

contract that is configured to display the appropriate login page:

4a Click Devices > Access Gateways > Edit > [Reverse Proxy Name] > [Proxy Service

Name] > Protected Resources.

4b For each protected resource that you have created a custom contract for, select the

protected resource, then configure it to use the custom contract.

5 Update the Access Gateway.

6 (Conditional) If the custom page does not display correctly, see Section 1.3.3,

“Troubleshooting Tips for Custom Login Pages,” on page 47.

novdocx (en) 19 February 2010

Adding Logic to the main.jsp File

You can modify the

main.jsp

file and use the contract URI to specify the login page to display. The

Identity Server must be running 3.1 SP1 or later to use this feature. Be aware of the following:

 The

main.jsp

file cannot be renamed, so any modifications you make to this file can be lost
whenever you upgrade the Identity Server. During the upgrade, you must select to restore
custom files or you must restore your modified file after the upgrade.

 Modifying the

Modifying the

 You can create multiple customized

custom2.jsp

 You can create multiple customized

main.jsp

main.jsp

, and

file requires knowledge of JSP programming and if/else statements.

file allows you to have the following type of configuration:

custom3.jsp

nidp.jsp

.

login.jsp

pages. For example:

custom1.jsp,

pages that request different login credentials.

For example:

login1.jsp: Configured to request username and password.

login2.jsp: Configured to request username, email, and password.

login3.jsp: Configured to request email and password.

With this type of configuration, you must create three different authentication contracts with an
authentication method with a JSP property defined for each of them. These contracts require the
types of values listed in the table below. The URI is defined so that it reflects the custom
and the custom

nidp.jps

that are used by the contract.

login.jsp

Configuring an Identity Server 43

Contract Configuration Details

Contract1 URI login1/custom1

Method1 Configured with the following JSP property:

Property Name: JSP

Property Value: login1

This method does not need a query property
unless you are using an attribute other than the cn
attribute for the username.

Contract2 URI login2/custom2

Method2 Configured with the following properties:

Property Name: JSP

Property Value: login2

novdocx (en) 19 February 2010

Property Name:

Property Value:

(mail=%Ecom_User_ID%)

Contract3 URI login3/custom3

Method3 Configured with the following properties:

Property Name: JSP

Property Value: login3

Property Name:

Property Value:

(mail=%Ecom_User_ID%)

Query

(&(objectclass=person)

)

Query

(objectclass=person)

The following procedure explains how to configure Access Manager to display these custom login
pages with custom credentials.

1 Create a unique method for each custom

login.jps

file:

1a In the Administration Console, click Devices > Identity Servers > Edit > Local > Methods.

1b Click New, then configure the following fields:

Display name: Specify a name for the method. You might want to use a name that
indicates which login page is assigned to this method.

Class: Select a name/password class.

Configure the other fields to match your requirements.

1c In the Properties section, add a Query property if the page uses custom credentials.

For example, to add an email address to the login prompts, add the following property:

Property Name:

Property Value:

44 Novell Access Manager 3.1 SP1 Identity Server Guide

Query

(&(objectclass=person)(mail=%Ecom_User_ID%)

)

If you are creating a method for Contract 1 in the example above (which prompts for a
username and password), you do not need to add a query property unless you are using an
attribute other than the cn attribute for the username.

1d In the Properties section, add a JSP property to specify which

login.jsp

file to use with

this method.

For example:

Property Name: JSP

Property Value: login2

1e Click Finish.

novdocx (en) 19 February 2010

1f If you have created more than one custom

login.jsp

file, repeat Step 1b through Step 1e

for each page.

To configure the scenario described in this section, repeat these steps for three login
pages.

2 Create a unique contract URI:

2a In the Administration Console, click Contracts.

2b Click New, then configure the following fields:

Display name: Specify a name for the contract. You might want to use a name that
indicates which login page is assigned to this contract.

URI: Specify a value that uniquely identifies the contract from all other contracts. No
spaces can exist in the URI field. You might want to use a name that indicates the custom
login page and custom credential page, such as

login1/custom1

.

Methods and Available Methods: Select the authentication method you configured in

Step 1.

2c Configure the other fields to meet your network requirements, then click Next.

2d Configure the authentication card, then click Finish.

2e (Conditional) If you have created multiple custom login pages, repeat Step 2b through

Step 2d for each page.

To configure the scenario described in this section, repeat these steps for /login2/custom2
and /login3/custom3.

2f Click OK, then update the Identity Server.

3 Modify the

3a Open the

main.jsp

Linux:

/var/opt/novell/tomcat5/webapps/nidp/jsp

Windows:

main.jsp

C:\Program Files\Novell\Tomcat\webapps\nidp\jsp

3b Near the top of the file, add the following line:

String strContractURI = hand.getContractURI();

This sets the strtContractURI variable to the value of the contract URI that is being used
for authentication. These lines should look similar to the following:

file:

file. The file is located in the following directory:

Configuring an Identity Server 45

<%
ContentHandler hand = new ContentHandler(request,response);
String strContractURI = hand.getContractURI();

// Is there a JSP defined on a class definition or a method
// definition that should be displayed as the main jsp here?
if (handler.contractDefinesMainJSP())
{
%>

3c After the if statement, add an

else if

statement for each contract URI you have created.

For example:

else if(strContractURI != null && strContractURI.equals("login1/
custom1"))
{
%>
<%@ include file="custom1.jsp" %>

<% }
else if(strContractURI != null && strContractURI.equals("login2/
custom2"))
{
%>
<%@ include file="custom2.jsp" %>

novdocx (en) 19 February 2010

else if(strContractURI != null && strContractURI.equals("login3/
custom3"))
{
%>
<%@ include file="custom3.jsp" %>

These

else if

 The first

to display the

 The second

configures it to display the

 The third

it to display the

statements set up three contracts for customized login pages:

else if

else if

statement specifies the URI of the login1 contract and configures it

custom1.jsp

else if

statement specifies the URI of the login2 contract and

page for authentication.

custom2.jsp

page for authentication.

statement specifies the URI of the login3 contract and configures

custom3.jsp

page for authentication.

Your file should look similar to the following:

<%@ page language="java" %>
<%@ page pageEncoding="UTF-8" contentType="text/html; charset=UTF-8"%>
<%@ page import="com.novell.nidp.*" %>
<%@ page import="com.novell.nidp.resource.jsp.*" %>
<%@ page import="com.novell.nidp.ui.*" %>
<%@ page import="com.novell.nidp.common.util.*" %>
<%@ page import="com.novell.nidp.liberty.wsf.idsis.apservice.schema.*"
%>

<%
ContentHandler hand = new ContentHandler(request,response);
String strContractURI = hand.getContractURI();

// Is there a JSP defined on a class definition
// or a method definition that should be displayed
// as the main jsp here?
if (hand.contractDefinesMainJSP())

46 Novell Access Manager 3.1 SP1 Identity Server Guide

{
%>
<%@ include file="mainRedirect.jsp" %>
<% }
else if(strContractURI != null && strContractURI.equals("login1/
custom1"))
{
%>
<%@ include file="custom1.jsp" %>

<% }
else if(strContractURI != null && strContractURI.equals("login2/
custom2"))
{
%>
<%@ include file="custom2.jsp" %>

else if(strContractURI != null && strContractURI.equals("login3/
custom3"))
{
%>
<%@ include file="custom3.jsp" %>

novdocx (en) 19 February 2010

<% } // This is the jsp used by default
else
{
%>
<%@ include file="nidp.jsp" %>
<% } %>

3d Copy the modified

main.jsp

file to each Identity Server in your cluster.

4 Back up your customized files.

5 For each resource that you have created a custom login page for, assign that resource to use the

contract that is configured to display the appropriate login page:

5a Click Devices > Access Gateways > Edit > [Reverse Proxy Name] > [Proxy Service

Name] > Protected Resources.

5b For each protected resource that you have created a custom contract for, select the

protected resource, then configure it to use the custom contract.

5c Update the Access Gateway.

6 (Conditional) If the custom page does not display correctly, see Section 1.3.3,

“Troubleshooting Tips for Custom Login Pages,” on page 47.

1.3.3 Troubleshooting Tips for Custom Login Pages

If your custom login page does not display or generates an error message, use the following
procedure to discover the root cause:

1 Set the Application option of Component File Logger Levels to debug, update the Identity

Server, attempt to log in, then view the log file.

Check for “Unable to compile” errors in the log file. If your custom page does not compile, a
blank page is displayed.

2 If you receive an “Unable to Find File” error, verify the value of the JSP property. Make sure

that the value does not contain the JSP extension as part of the filename.

Configuring an Identity Server 47

3 If you see pages that you have deleted or pages where your modifications have not been

implemented:

3a Delete the

Linux:

nidp

directory in the Tomcat work directory on each Identity Server.

/var/opt/novell/tomcat5/work/Catalina/localhosts/nidp

novdocx (en) 19 February 2010

Windows:

C:\Program Files\Novell\Tomcat\work\Catalina\localhosts\nidp

3b Restart Tomcat on each Identity Server.

1.4 Customizing the Identity Server Logout Page

You can also use the following methods to modify the Identity Server logout page:

 Section 1.4.1, “Rebranding the Logout Page,” on page 48

 Section 1.4.2, “Replacing the Logout Page with a Custom Page,” on page 48

To customize the logout page when the user logs out of an Access Gateway protected resource, see
“Customizing Logout Requests” in the Novell Access Manager 3.1 SP1 Access Gateway Guide.

1.4.1 Rebranding the Logout Page

The branding in the header of the logout page is controlled by the branding of the
you have modified this file for a customized login, the same branding appears in the logout page.
For information on how to modify

nidp.jsp

for logos, titles, and colors, see “Rebranding the

Header” on page 34.

IMPORTANT: Save a copy of your modified

nipd.jsp

file. Every time you upgrade your Identity

Server, you’ll need to restore this file.

nidp.jsp

file. If

1.4.2 Replacing the Logout Page with a Custom Page

You can create your own logout page and configure the Identity Server to use it. To do this, you
need to modify the

logoutSuccess.jsp

directory:

Linux:

Windows Server 2003:

Windows Server 2008:

The

/var/opt/novell/tomcat5/webapps/nidp/jsp

\Program Files\Novell\Tomcat\webapps\nidp\jsp

\Program Files (x86)\Novell\Tomcat\webapps\nidp\jsp

logoutSuccess.jsp

file is called in a frame from the
to display what you want or you can modify it to redirect the user to your custom page. One way to
provide redirection is to replace the information in the <body> element of the file with something
similar to the following:

<body>
<script language="JavaScript">
top.location.href='http://<hostname/path>';
</script>
</body>

Replace the <hostname/path> string with the location of your customized logout page.

file on the Identity Server. It is located in the following

nidp.jsp

file. You can modify the file

48 Novell Access Manager 3.1 SP1 Identity Server Guide

novdocx (en) 19 February 2010

IMPORTANT: Save a copy of your modified

logoutSuccess.jsp

file. Every time you upgrade

your Identity Server, you will need to restore this file.

1.5 Enabling Role-Based Access Control

Role-based access control is used to provide a convenient way to assign a user to a particular job
function or set of permissions within an enterprise, in order to control access. In Access Manager,
you assign users to roles, based on attributes of their identity, and then associate authorization
policies to the role.

For a complete discussion on creating and configuring role policies, see “Creating Role Policies” in
the Novell Access Manager 3.1 SP1 Policy Management Guide.

In order for a role to be assigned to users at authentication, you must enable it for the Identity Server
configuration.

1 In the Administration Console, click Devices > Identity Servers > Servers > Edit > Roles.

2 Click the role policy’s check box, then click Enable.

3 To disable the role policy, click the role policy’s check box, then click Disable.

4 After enabling or disabling role policies, update the Identity Server configuration on the

Servers tab.

1.6 Using netHSM for the Signing Key Pair

netHSM* is a hardware security module (HSM) from nCipher*. The module is attached to the
network and provides cryptographic resources for multiple servers. Keys stored in a netHSM
keystore are secure because the key material can never be exposed outside of the module.

Access Manager has not been tested with any other HSM products; it has only been tested with the
netHSM module from nCipher.

Figure 1-5 illustrates a simple netHSM configuration with an Identity Server as a netHSM client.

Figure 1-5 A Simple netHSM Configuration

netHSM Server

Remote File System &

netHSM Client

Identity Server &

netHSM Client

Configuring an Identity Server 49

Access Manager allows you to use netHSM to store and manage the signing key pair of the Identity
Server. You must use the Administration Console to store and manage the other Access Manager
certificates. Access Manager uses the Java Security provider of the netHSM server to interact with
the netHSM server.

This section describes the following about the netHSM implementation:

 Section 1.6.1, “Understanding How Access Manager Uses Signing and Interacts with the

netHSM Server,” on page 50

 Section 1.6.2, “Configuring the Identity Server for netHSM,” on page 52

1.6.1 Understanding How Access Manager Uses Signing and
Interacts with the netHSM Server

The netHSM server provides a signing certificate that is used instead of the one provided by Access
Manager. Requests, responses, assertions, or payloads can be signed when there are interactions
during single sign-on or during attribute queries between service providers and identity providers
using any of the SAML1.1, SAML2, Liberty ID-FF, Liberty ID-WSF, or ID-SIS protocols.

novdocx (en) 19 February 2010

 “Access Manager Services That Use the Signing Certificate” on page 50

 “Understanding the Interaction of the netHSM Server with Access Manager” on page 51

Access Manager Services That Use the Signing Certificate

The following services can be configured to use signing:

 “Protocols” on page 50

 “SOAP Back Channel” on page 50

 “Profiles” on page 51

Protocols

The protocols can be configured to sign authentication requests.

To view your current configuration:

1 In the Administration Console, click Devices > Identity Servers > Edit.

2 In the Identity Provider section, view the setting for the Require Signed Authentication

Requests option. If it is selected, all authentication requests from identity providers are signed.

3 In the Identity Consumer section, view the settings for the Require Signed Assertions and Sign

Authentication Requests options. If these options are selected, assertions and authentication

requests are signed.

SOAP Back Channel

The SOAP back channel is the channel that the protocols use to communicate directly with a
provider. The SOAP back channel is used for artifact resolutions and attribute queries for the
Identity Web Services Framework.

To view your current configuration for the SOAP back channel:

1 In the Administration Console, click Devices > Identity Servers > Edit.

50 Novell Access Manager 3.1 SP1 Identity Server Guide

2 Select the protocol (Liberty, SAML 1.1, or SAML 2.0), then click the name of an identity

e

provider or service provider.

3 Click Access.

4 View the Security section. If the Message Signing option is selected, signing is enabled for the

SOAP back channel.

Profiles

Any of the Web Service Provider profiles can be enabled for signing by configuring them to use
X.509 for their Security Mechanism.

To view your current configuration:

1 In the Administration Console, click Devices > Identity Servers > Edit > Liberty > Web S ervic e

Provider.

2 Click the name of a profile, then click Descriptions.

3 Click the Description Name.

4 If either Peer entity = None, Message=X509 or Peer entity = MutualTLS, Message=X509 has

been selected as the security mechanism, signing has been enabled for the profile.

novdocx (en) 19 February 2010

Understanding the Interaction of the netHSM Server with Access Manager

Figure 1-6 outlines one of the basic flows that might occur during single sign-on to the Identity

Server when authentication requests have been configured for signing.

Figure 1-6 Basic Flow for an Authentication Request Using netHSM

netHSM Server

Identity Server

and netHSM Client

3

(out-of-band)

(out-of-band)

4

2

4

1

Browser

5

Access Gateway Web Server Web Pag

Remote File System

and netHSM Client

6

7

1. The user requests the Access Gateway to provide access to a protected resource.

2. The Access Gateway redirects the user to the Identity Server, which prompts the user for a
username and password.

3. The Identity Server authenticates the user. If signing is enabled, the payload is signed by the
netHSM server through the Java JSSE security provider.

Configuring an Identity Server 51

4. The Identity Server returns the authentication artifact to the Access Gateway.

5. The Embedded Service Provider of the Access Gateway retrieves the user’s credentials from
the Identity Server.

6. The Access Gateway verifies that the credentials allow the user access to the resource, then
sends the request to the Web server.

7. The Web server returns the requested Web page.

1.6.2 Configuring the Identity Server for netHSM

 “Prerequisites for Using netHSM” on page 52

 “Configuring the Identity Server to Be a netHSM Client” on page 52

 “Creating the nCipher Signing Key Pair” on page 54

 “Configuring the Identity Server to Use the netHSM Certificate” on page 59

 “Verifying the Use of the nCipher Key Pair” on page 63

 “Troubleshooting the netHSM Configuration” on page 64

novdocx (en) 19 February 2010

Prerequisites for Using netHSM

 An installed and configured netHSM server.

 An installed and configured remote file system with the netHSM client.

 An installed Identity Server, assigned to a cluster configuration.

For instructions on a basic setup that assigns the Identity Server to a cluster configuration, see
“Creating a Basic Identity Server Configuration” in the Novell Access Manager 3.1 SP1 Setup

Guide.

The following instructions describe one way to integrate the Identity Server with a netHSM server.
Other ways are possible.

Configuring the Identity Server to Be a netHSM Client

The following instructions are based on nCipher hardware, but you should be able to adapt them for
your hardware. The instructions explain how to configure the Identity Server so that it can
communicate with both the nCipher server and the remote file system server, how to create a signing
key pair and its keystore, how to copy these them to the Identity Server, and how to synchronize the
changes with the remote file system server.

root

1 At the Identity Server, log in as

The nCipher software installs files in the

and install the netHSM client software.

/opt/nfast

directory on Linux and in the

C:\nfast

directory on Windows. It creates an nfast user and group. Check your netHSM documentation
for the specific steps.

2 (Conditional) If your Identity Server cluster configuration contains more than one Identity

Server, install the netHSM client software on the other Identity Servers in the cluster.

3 At the netHSM server, configure the server to allow the Identity Server to be a client.

Check your netHSM documentation for the specific steps.

52 Novell Access Manager 3.1 SP1 Identity Server Guide

4 (Conditional) If your Identity Server cluster configuration contains more than one Identity

Server, configure the netHSM server to allow the other Identity Servers in the cluster to be a
client.

5 At the Identity Server, enroll the client to use the server:

5a To get the ESN and hash numbers for the enroll command, enter the following command:

Linux:

/opt/nfast/bin/anonkneti <IP_address>

novdocx (en) 19 February 2010

Windows:

C:\nfast\bin>anonkneti <IP_address>

Replace <IP_address> with the IP address of the netHSM server.

5b To enroll the client, enter the following command:

Linux:

Windows:

/opt/nfast/bin/nethsmenroll -p <IP_address> <ESN> <hash>

C:\nfast\bin>nethsmenroll -p <IP_address> <ESN> <hash>

Replace <IP_address> with the IP address of the netHSM server. Replace <ESN> and
<hash> with the values copied from the

anonkneti

command.

6 (Conditional) If the Identity Server and the Administration Console are installed on the same

machine, modify the 9000 and 9001 TCP ports:

6a In a text editor, open the

Linux:

Windows:

/opt/novell/devman/share/conf

C:\Program Files\Novell\Tomcat\webapps\roma\WEB-INF\conf

sc.conf

file located in the following directory:

6b Change the ports from 9000 and 9001 to another value, such as 9010 and 9011.

The lines should look similar to the following:

<stringParam name="ExecutorPort" value="9010" />
<stringParam name="SchedulerPort" value="9011" />

6c Save the changes.

6d Restart Tomcat:

Linux: Enter the following command:

/etc/init.d/novell-tomcat5 restart

Windows: Enter the following commands:

net stop Tomcat5

net start Tomcat5

6e (Conditional) If other Identity Servers in the cluster contain an Administration Console,

repeat Step 6.

7 At the Identity Server, enable the netHSM client so that it uses TCP:

7a Enter the following command:

Linux:

Windows:

/opt/nfast/bin/config-serverstartup -sp

C:\nfast\bin>config-serverstartup -sp

7b To restart the nfast client:

Linux: Enter the following command:

/opt/nfast/sbin/init.d-nfast restart

Windows: Enter the following commands:

Configuring an Identity Server 53

C:\nfast\bin>net stop "nfast server"

C:\nfast\bin>net start "nfast server"

8 Configure communication to the remote file system server. In this sample configuration, the

remote file system is installed on a Windows machine.

8a At the remote file system server, enable communication with the Identity Server. For a

Windows machine, enter the following command:

C:\nfast\bin\rfs-setup.exe --gang-client --write-noauth <address>

Replace <address> with the IP address of the Identity Server.

8b At the Identity Server, enable communication with the remote file system server. For

nCipher, enter the following command:

Linux:

Windows:

/opt/nfast/bin/rfs-sync --setup --no-authenticate <address>

C:\nfast\bin>rfs-sync --setup --no-authenticate <address>

Replace <address> with the IP address of the remote file system server.

8c At the Identity Server, initialize synchronization with the remote file system server.

Linux: Enter the following commands:

novdocx (en) 19 February 2010

/opt/nfast/bin/rfs-sync –-update

/opt/nfast/bin/rfs-sync –-commit

Windows: Enter the following commands:

C:\nfast\bin>rfs-sync --update

C:\nfast\bin>rfs-sync --commit

The first command reads updates from the remote file system server and downloads files

/opt/nfast/kmdata/local

to the

C:\nfast\kmdata\local

directory on Windows. The second command writes local

directory on Linux and the

changes to the remote file system server.

9 Continue with “Creating the nCipher Signing Key Pair” on page 54.

Creating the nCipher Signing Key Pair

IMPORTANT: Because of Access Manager configuration conflicts, you need to use a netHSM
client other than the Identity Server. The remote file system server is a netHSM client, or if you have
configured another device as a client, you can use that device.

The following commands are specific to nCipher; it does not come with a tool to generate a key pair
and CSR. nCipher also uses a unique keystore of type

nCipher.sworld

.

nCipher supports both a Windows and a Linux netHSM client.

 If you have a Windows netHSM client, the command is located in the following directory:

c:\Program Files\Java\jdk1.5.0_14\jre\bin\java

 If you have Linux netHSM client, the command is located in the following directory:

/opt/novell/java/bin/java

54 Novell Access Manager 3.1 SP1 Identity Server Guide

To create a new key pair for nCipher:

novdocx (en) 19 February 2010

1 On a netHSM client, add the nCipher provider to the provider list of the

1a In a text editor, open the

security\java.security

C:\Program Files\Java\jdk1.5.0_14\jre\lib\

file.

java.security

1b Add the following lines to the top of the list of providers:

security.provider.1=com.ncipher.fixup.provider.nCipherRSAPrivateEncry
pt
security.provider.2=com.ncipher.provider.km.nCipherKM

The provider section should look similar to the following:

#
# List of providers and their preference orders (see above):
#
security.provider.1=com.ncipher.fixup.provider.nCipherRSAPrivateEncry
pt
security.provider.2=com.ncipher.provider.km.nCipherKM
security.provider.3=sun.security.provider.Sun
security.provider.4=sun.security.rsa.SunRsaSign
security.provider.5=com.sun.net.ssl.internal.ssl.Provider
security.provider.6=com.sun.crypto.provider.SunJCE
security.provider.7=sun.security.jgss.SunProvider
security.provider.8=com.sun.security.sasl.Provider

1c Save your changes.

2 Add the nfast libraries to the CLASSPATH for Java:

For a Windows client, add the following paths:

c:\nfast\java\classes\keysafe.jar;c:\nfast\java\classes\nfjava.jar
;c:\nfast\java\classes\kmjava.jar;c:\nfast\java\classes\kmcsp.jar;
c:\nfast\java\classes\jutils.jar;c:\nfast\java\classes\jcetools.
jar;c:\nfast\java\classes\spp.jar;c:\nfast\java\classes\rsaprivenc
.jar;

For a Linux client, add the following paths and export them:

/opt/nfast/java/classes/nfjava.jar:/opt/nfast/java/classes/
kmjava.jar:/opt/nfast/java/classes/kmcsp.jar:/opt/nfast/java/
classes/spp.jar:/opt/nfast/java/classes/rsaprivenc.jar:/opt/nfast/
java/classes/jutils.jar:/opt/nfast/java/classes/jcetools.jar:/opt/
nfast/java/classes/keysafe.jar

3 Create a directory for the keystore and change to that directory.

4 On a Windows client, enter the following command to create a new key in a keystore:

"c:\Program Files\Java\jdk1.5.0_14\jre\bin\java" -Dprotect=module

-DignorePassphrase=true sun.security.tools.KeyTool -genkey -v

-alias od93 -keyalg RSA -keystore AMstore.jks -storetype
nCipher.sworld -provider com.ncipher.provider.km.nCipherKM

Enter your values for the following parameters:

file:

Parameter Description

-Dprotect=module

Only required if you want the keystore to be
module protected.

Configuring an Identity Server 55

Parameter Description

novdocx (en) 19 February 2010

-DignorePassphrase=true

sun.security.tools.KeyTool

-alias

-keyalg

-keystore

-storetype

-provider

Only required if you want the keystore to be
module protected.

The name of the keytool command

A name that helps you identify the key. In this

od93

sample configuration, the name is

The security algorithm.

A name for the keystore. In this sample
configuration, the name is

The type of keystore. For nCipher, this must be
set to

nCipher.sworld

The name of the providerClass and
providerName. This is the provider that you
added to the

java.security

AMstore.jks

.

file in Step 1.

.

.

The tool prompts you for a password for the keypass and the storepass. They must be the same
password if you are going to use card set protection rather than module protection.

The tool also prompts you for the certificate subject name (first name, last name, organization,
organizational unit, locality, state or providence, and country).

5 To generate a certificate request from a key in the keystore, enter the following command:

"c:\Program Files\Java\jdk1.5.0_14\jre\bin\java" -Dprotect=module

-DignorePassphrase=true sun.security.tools.KeyTool -certreq -alias
od93 -file cert.csr -keypass mypwd -keystore AMstore.jks -storepass
mypwd -storetype nCipher.sworld -provider
com.ncipher.provider.km.nCipherKM

Enter your values for the following parameters:

Parameter Description

-Dprotect=module

-DignorePassphrase=true

sun.security.tools.KeyTool

-certreq

-alias

-file

-keypass

56 Novell Access Manager 3.1 SP1 Identity Server Guide

Only required if you want the keystore to be
module protected.

Only required if you want the keystore to be
module protected.

The name of the keytool command

The parameter that makes this a certificate
request.

A name that helps you identify the certificate
request. In this sample configuration, the name
is od93.

The name to be given to the certificate signing
request file. In this sample configuration, the
name is

The password for the key. In this sample
configuration, the password is mypwd.

cert.csr

.

Parameter Description

novdocx (en) 19 February 2010

-keystore

-storepass

-storetype

-provider

A name for the keystore. In this sample
configuration, the name is

The password for the keystore. In this sample
configuration, the password is mypwd.

The type of keystore. For nCipher, this must be
set to

nCipher.sworld

The name of the providerClass and
providerName.

AMstore.jks

.

.

6 Take the CSR created in Step 5 to a certificate authority. The CA needs to send you a DER-

encoded public certificate. The CA also needs to send you the public certificate that it used to
create the certificate and the public certificates for any CAs in the chain.

7 Load the public certificate of the CA into the keystore by entering the following command:

"c:\Program Files\Java\jdk1.5.0_14\jre\bin\java" -Dprotect=module

-DignorePassphrase=true sun.security.tools.KeyTool -import -alias
publicca –file certca.cer -keystore Amstore.jks -storetype
nCipher.sworld -provider com.ncipher.provider.km.nCipherKM

Enter your values for the following parameters:

Parameter Description

-Dprotect=module

Only required if you want the keystore to be
module protected.

-DignorePassphrase=true

sun.security.tools.KeyTool

-import

-alias

-file

-keystore

-storetype

-provider

Only required if you want the keystore to be
module protected.

The name of the keytool command

The parameter that makes this an import
request.

A name that helps you identify that this is the
public certificate from the CA. In this sample
configuration, the name is

The name of the CA certificate file. In this
sample configuration, the name is certca.cer.

A name for the keystore. In this sample
configuration, the name is

The type of keystore. For nCipher, this must be

nCipher.sworld

set to

The name of the providerClass and
providerName.

publicca

AMstore.jks

.

.

The tool prompts you for the keystore password and asks whether you want to trust the
certificate.

8 (Conditional) Repeat Step 7 for each CA in the chain, giving each CA a unique alias.

.

9 Import the signed certificated received from the CA by entering the following command:

Configuring an Identity Server 57

"c:\Program Files\Java\jdk1.5.0_14\jre\bin\java" -Dprotect=module

-DignorePassphrase=true sun.security.tools.KeyTool -import -alias
od93 –file signcert.der -keystore AMstore.jks -storepass mypwd

-storetype nCipher.sworld -provider
com.ncipher.provider.km.nCipherKM

Enter your values for the following parameters:

Parameter Description

novdocx (en) 19 February 2010

-Dprotect=module

-DignorePassphrase=true

sun.security.tools.KeyTool

-import

-alias

-file

-keystore

-storepass

-storetype

Only required if you want the keystore to be
module protected.

Only required if you want the keystore to be
module protected.

The name of the keytool command

The parameter that makes this an import
request.

A name that helps you identify that this is the
signing key pair from the CA. It needs to be the
same alias you specified when you created the
keystore in Step 4. In this sample configuration,

od93

the name is

The name of the signing certificate file from the
CA. In this sample configuration, the name is

signcert.der

A name for the keystore. In this sample
configuration, the name is

The password for the keystore. In this sample
configuration, the password is

The type of keystore. For nCipher, this must be
set to

nCipher.sworld

.

.

AMstore.jks

mypwd

.

.

.

-provider

10 (Optional) To verify that the certificates have been added to the keystore, enter the following

command:

"c:\Program Files\Java\jdk1.5.0_14\jre\bin\java" -Dprotect=module

-DignorePassphrase=true sun.security.tools.KeyTool -list -v

-keystore AMstore.jks -storetype nCipher.sworld -provider
com.ncipher.provider.km.nCipherKM

The keystore should contain at least two certificates. The certificate that you created should
now be issued by the CA you used, and the public certificate of the CA should be there as the
owner and the issuer.

idp

11 Copy the keystore to the

Linux:

Windows:

/opt/novell/devman/jcc/certs/idp

C:\Program Files\Novell\devman\jcc\certs\idp

directory on the Identity Server.

The keystore is found on the netHSM client in the directory specified by the -keystore
parameter when you created the keystore. See Step 4.

58 Novell Access Manager 3.1 SP1 Identity Server Guide

The name of the providerClass and
providerName.

12 Synchronize the Identity Server with the remote file system server.

Linux: Enter the following commands:

/opt/nfast/bin/rfs-sync –-update

/opt/nfast/bin/rfs-sync –-commit

Windows: Enter the following commands:

C:\nfast\bin>rfs-sync --update

C:\nfast\bin>rfs-sync --commit

13 (Conditional) If the cluster configuration contains more than one Identity Server, complete the

following steps for each cluster member:

13a Copy the keystore to the cluster member. Copy it to the following directory:

Linux:

Windows:

/opt/novell/devman/jcc/certs/idp

C:\Program Files\Novell\devman\jcc\certs\idp

novdocx (en) 19 February 2010

13b Make sure the

novlwww

user has at least read rights.

13c Use the netHSM client to synchronize the cluster member with the remote file system

server.

Linux: Enter the following commands:

/opt/nfast/bin/rfs-sync –-update

/opt/nfast/bin/rfs-sync –-commit

Windows: Enter the following commands:

C:\nfast\bin>rfs-sync --update

C:\nfast\bin>rfs-sync --commit

14 Continue with “Configuring the Identity Server to Use the netHSM Certificate” on page 59.

Configuring the Identity Server to Use the netHSM Certificate

The following procedure requires you to modify the classpath for Tomcat, and this procedure is
quite different, depending upon whether you have a Linux and Windows Identity Server:

 “Configuring a Linux Identity Server for the Certificate” on page 59

 “Configuring a Windows Identity Server for the Certificate” on page 61

Configuring a Linux Identity Server for the Certificate

1 At the Identity Server, log in as

2 Add the nfast jar files to the classpath.

Because the Identity Server runs as a Tomcat service, the following steps explain how to
modify the classpath for Tomcat.

2a In an editor, open the

2b To the

CLASSPATH="$JAVA_HOME"/lib/tools.jar

/opt/nfast/java/classes

the

root

.

/opt/novell/tomcat5/bin/dtomcat5

line, add the following classes from

directory:

file.

Configuring an Identity Server 59

nfjava.jar
kmjava.jar
kmcsp.jar
spp.jar
rsaprivenc.jar
jutils.jar:
jcetools.jar
keysafe.jar

Your line should look similar to the following:

CLASSPATH="$JAVA_HOME"/lib/tools.jar:/opt/nfast/java/classes/
nfjava.jar:/opt/nfast/java/classes/kmjava.jar:/opt/nfast/java/
classes/kmcsp.jar:/opt/nfast/java/classes/spp.jar:/opt/nfast/
java/classes/rsaprivenc.jar:/opt/nfast/java/classes/
jutils.jar:/opt/nfast/java/classes/jcetools.jar:/opt/nfast/
java/classes/keysafe.jar

2c Save your changes.

3 Add the

usermod novlwww -G nfast

novlwww

user to the

nfast

group by entering the following command:

4 Add the netHSM certificate configuration lines to the

4a In a text editor, open the

/var/opt/novell/tomcat5/conf/tomcat5.conf

4b Add the following lines:

JAVA_OPTS="${JAVA_OPTS} -Dcom.novell.nidp.extern.config.file=
/var/opt/novell/tomcat5/webapps/nidp/WEB-INF/classes/
externKeystore.properties"

tomcat5.conf

novdocx (en) 19 February 2010

file:

file.

JAVA_OPTS="${JAVA_OPTS} -Dprotect=module

-DignorePassphrase=true"

The first line specifies the location of the properties file. You can specify another location.

The second line is required only if you want the keystore to be module protected rather
than card protected.

5 Configure the

externKeystore.properties

5a In a text editor, create an

tomcat5/webapps/nidp/WEB-INF/classes

If you specified a different location for this file in Step 4, use that location.

5b Add the following lines:

com.novell.nidp.extern.signing.providerClass=com.ncipher.provider.km.
nCipherKM
com.novell.nidp.extern.signing.providerName=nCipherKM
com.novell.nidp.extern.signing.keystoreType=nCipher.sworld
com.novell.nidp.extern.signing.keystoreName=/opt/novell/devman/jcc/
certs/idp/AMstore.jks
com.novell.nidp.extern.signing.keystorePwd=mypwd
com.novell.nidp.extern.signing.alias=od93
com.novell.nidp.extern.signing.keyPwd=mypwd

file to use the nCipher key and keystore:

externKeystore.properties

directory.

file in the

/var/opt/novell/

60 Novell Access Manager 3.1 SP1 Identity Server Guide

Enter your values for the following variables:

Var iable Val ue

novdocx (en) 19 February 2010

<provider_class

<provider_name

<keystore_type>

<keystore_name>

<keystore_pwd>

<key_alias>

<key_pwd>

> The name of the providerClass. For nCipher, this must be set to

com.ncipher.provider.km.nCipherKM

> The name of the provider. For nCipher, this must be set to

nCipherKM

The type of keystore. For nCipher, this must be set to

nCipher.sworld

The name you specified when you created the keystore. In this
sample configuration, the name is

When using module-protected keys, the keystore password must be
null. For example:

com.novell.nidp.extern.signing.keystorePwd=

The alias you created for the key when you created the key. In this
sample configuration, the name is

When using module-protected keys, the key password must be null.
For example:

com.novell.nidp.extern.signing.keyPwd=

.

.

AMstore.jks

od93

.

6 To restart Tomcat, enter the following command:

/etc/init.d/novell-tomcat5 restart

7 Continue with “Verifying the Use of the nCipher Key Pair” on page 63.

.

.

Configuring a Windows Identity Server for the Certificate

1 At the Identity Server, log in as the Windows administrator.

2 Add the nfast jar files to the classpath.

Because the Identity Server runs as a Tomcat service, the following steps explain how to
modify the classpath for Tomcat.

2a Run the

tomcat5w.exe

utility located in the

C:\Program Files\Novell\Tomcat\bin

directory.

2b Click the Java tab.

2c In the Java Classpath text box add the following to the end of the path:

";C:\nfast\java\classes\jcetools.jar;C:\nfast\java\classes\jutils.jar
;C:\nfast\java\classes\keysafe.jar;C:\nfast\java\classes\kmcsp.jar;C:
\nfast\java\classes\kmjava.jar;C:\nfast\java\classes\nfjava.jar;C:\nf
ast\java\classes\rsaprivenc.jar;C:\nfast\java\classes\spp.jar"

2d Save your changes.

3 Add the netHSM certificate configuration lines to the

3a Run the

tomcat5w.exe

utility located in the

tomcat5.conf

C:\Program Files\Novell\Tomcat\bin

file:

directory.

3b Click the Java tab.

Configuring an Identity Server 61

3c In the Java Options text box, add the following as three separate lines:

­Dcom.novell.nidp.extern.config.file=C:\PROGRA~1\Novell\Tomcat\webapps
\nidp\WEB-INF\classes\externKeystore.properties

-Dprotect=module

-DignorePassphrase=true

The first line specifies the location of the properties file. For readability, it has been
wrapped and indented. Remove the extra white space when creating the entry in the file.
You can specify another location.

The second line is required only if you want the keystore to be module protected rather
than card protected.

4 Configure the

externKeystore.properties

file to use the nCipher key and keystore:

novdocx (en) 19 February 2010

4a In a text editor, create an

Files\Novell\Tomcat\webapps\nidp\WEB-INF\classes

externKeystore.properties

file in the

directory.

C:\Program

If you specified a different location for this file in Step 3, use that location.

4b Add the following lines:

com.novell.nidp.extern.signing.providerClass=com.ncipher.provider.km.
nCipherKM
com.novell.nidp.extern.signing.providerName=nCipherKM
com.novell.nidp.extern.signing.keystoreType=nCipher.sworld
com.novell.nidp.extern.signing.keystoreName=C:\\Program
Files\\Novell\\
devman\\jcc\\certs\\idp\\AMstore.jks
com.novell.nidp.extern.signing.keystorePwd=mypwd
com.novell.nidp.extern.signing.alias=od93
com.novell.nidp.extern.signing.keyPwd=mypwd

The

com.novell.nidp.extern.signing.keystoreName

line is wrapped and indented
for readability. All extra white space needs to be removed in the file entry. The double
slashes in the path are required.

Enter your values for the following variables:

Var iable Val ue

<provider_class

> The name of the providerClass. For nCipher, this must be set to

com.ncipher.provider.km.nCipherKM

.

<provider_name

<keystore_type>

<keystore_name>

<keystore_pwd>

<key_alias>

62 Novell Access Manager 3.1 SP1 Identity Server Guide

> The name of the provider. For nCipher, this must be set to

nCipherKM

The type of keystore. For nCipher, this must be set to

nCipher.sworld

The name you specified when you created the keystore. In this
sample configuration, the name is

When using module-protected keys, the keystore password must be
null. For example:

com.novell.nidp.extern.signing.keystorePwd=

The alias you created for the key when you created the key. In this
sample configuration, the name is

.

.

AMstore.jks

od93

.

.

Var iable Val ue

novdocx (en) 19 February 2010

<key_pwd>

When using module-protected keys, the key password must be null.
For example:

com.novell.nidp.extern.signing.keyPwd=

5 To restart Tomcat, enter the following commands:

net stop Tomcat5

net start Tomcat5

6 Continue with “Verifying the Use of the nCipher Key Pair” on page 63.

Verifying the Use of the nCipher Key Pair

After you have configured the Identity Server to use the nCipher key pair and have restarted Tomcat,
the metadata of the Identity Server indicates that the nCipher key pair is being used for the signing
certificate.

1 In a browser, enter the following URL:

http://<DNS_name>:8080/nidp/idff/metadata

Replace <DNS_name> with the DNS name of your Identity Server.

2 Search for the following string:

<md:KeyDescriptor use="signing">

3 Copy the certificate text between the

ds:X509Certificate>

tags

<ds:X509Certificate>

and the

</

4 Paste the text into a text editor.

5 Delete the

-----BEGIN CERTIFICATE-----

6 Delete the

-----END CERTIFICATE-----

7 Save the file as a text file with a .

<ds:X509Certificate>

</ds:X509Certificate>

tag and replace it with the following text:

cer

tag and replace it with the following text:

extension.

8 Open the file in Internet Explorer.

9 View the certificate details.

If the Identity Server is using the nCipher signing certificate, the certificate is issued by your
CA and the name the certificate is issued to is the name you specified for the certificate.

If the Identity Server is using the Access Manager certificate, the certificate is issued by the
Organizational CA and the certificate name is test-signing. For troubleshooting information,
see “Troubleshooting the netHSM Configuration” on page 64.

Configuring an Identity Server 63

Troubleshooting the netHSM Configuration

To discover potential configuration errors:

1 Verify that you have not enabled the data encryption of resource IDs. There is a known issue

with this feature and the Apache libraries in a multi-provider environment. Because of this
issue, netHSM is not compatible with encrypting the resource IDs.

1a In the Administration Console, click Devices > Identity Servers > Edit > Liberty > Web

Service Provider.

1b Click a profile, then check the setting for the Have Discovery Encrypt This Service’s

Resource Ids option.

1c If the option is selected, deselect it, then click OK.

1d Verify that all profiles have been configured so that they do not encrypt the resource IDs.

2 View the nfast log files:

Linux:

Windows:

/opt/nfast/log

C:\nfast\log

novdocx (en) 19 February 2010

When there is a port conflict,

nFast server: Notice: Using tcp socket local:9000
nFast server: Fatal error during startup: Operating system call failed:
bind tcp socket, Address already in use

logfile

contains entries similar to the following:

For information on how to change the port, see Step 6 on page 53. For other errors, consult the
netHSM documentation.

3 (Linux only) If the

debug.log

files, the Identity Server is halted because it cannot read the keystore. The Health

novlwww

user does not have rights to the

cmdadp.log

and

cmdadp-

page of the Identity Server displays the following error:

The following error occurred during the identity server configuration.
Unable to read keystore: /opt/novell/devman/jcc/certs/idp/AMstore45.jks

To correct the error:

3a View the rights for the nfast log files with the following command:

ll /opt/nfast/log

Your listing should look similar to the following:

-rw-r--r-- 1 novlwww nfast 0 Apr 11 11:50 cmdadp-debug.log

-rw-r--r-- 1 novlwww nfast 134 Apr 11 11:50 cmdadp.log

-rw-r----- 1 root nfast 43 Apr 11 11:49 debug

-rw-r----- 1 nfast nfast 5 Apr 11 11:49 hardserver.pid

-rw-r----- 1 nfast nfast 3057 Apr 11 11:50 logfile

If

novlwww

is not listed as the owner of the

cmdadp.log

and

cmdadp-debug.log

files,

continue with Step 3b.

If

novlwww

is listed as the owner of the files with rw permissions, log file ownership is not

the source of your problem. Continue with Step 4.

3b Stop Tomcat with the following command:

/etc/init.d/novell-tomcat5 stop

3c Stop nfast with the following command:

/opt/nfast/sbin/init.d-nfast stop

64 Novell Access Manager 3.1 SP1 Identity Server Guide

novdocx (en) 19 February 2010

3d Delete all the log files in the

/opt/nfast/log

directory.

3e Start nfast with the following command:

/opt/nfast/sbin/init.d-nfast start

3f Start Tomcat with the following command

/etc/init.d/novell-tomcat5 start

3g Wait a minute, then list the files in the

/opt/nfast/log

directory.

The nfast client creates the log files and assigns the correct owners and rights.

4 Enable Identity Server logging and view the

catalina.out

file.

4a In the Administration Console, click Devices > Identity Servers > Edit > Logging.

4b Configure the following options:

File Logging: Specify enabled.

Echo to Console: Select this option.

Component File Logger Levels: Set Application to debug.

4c Click OK, then update the Identity Server.

4d Delete the current

catalina.out

file in the

/var/opt/novell/tomcat5/logs

directory.

4e Restart Tomcat by entering the following command:

/etc/init.d/novell-tomcat5 restart

4f To tail the

tail -f /var/opt/novell/tomcat5/logs/catalina.out

catalina.out

file, enter the following command:

4g Search for a list of providers. When nCipher is working, the file contains entries similar to

the following and nCipher entries:

Security Providers:
SUN: 1.42
SUN (DSA key/parameter generation; DSA signing; SHA-1, MD5
digests; SecureRandom; X.509 certificates; JKS keystore; PKIX
CertPathValidator; PKIX CertPathBuilder; LDAP, Collection CertStores)
SunJSSE: 1.42
Sun JSSE provider(implements RSA Signatures, PKCS12, SunX509
key/trust factories, SSLv3, TLSv1)
SunRsaSign: 1.42
SUN's provider for RSA signatures
SunJCE: 1.42
SunJCE Provider (implements DES, Triple DES, AES, Blowfish,
PBE, Diffie-Hellman, HMAC-MD5, HMAC-SHA1)
SunJGSS: 1.0
Sun (Kerberos v5)
nCipherRSAPrivateEncrypt: 1.008004

RSA private key encrypt handling provider
nCipherKM: 1.008004
nCipher Secure Key Management

BC: 1.28
BouncyCastle Security Provider v1.28
SAML: 1.0
SAML SASL Mechanism

Configuring an Identity Server 65

novdocx (en) 19 February 2010

4h (Conditional) If the

catalina.out

file does not contain any entries for providers, check

for the following errors:

 Check the Health of the Identity Server. If the status is red, use the error message to

resolve the issue.

 Make sure the

 Verify that the

novlwww

externKeystore.properties

user has read rights to the keystore.

file has all the required lines with

valid values. See Step 5 on page 60.

 Verify that the

tomcat5.conf

file is configured correctly. See Step 4 on page 60.

5 Enable netHSM logging.

This logging feature is very verbose. It should be turned on only while you are debugging a
problem. If it is left on, your machine can quickly run out of disk space.

5a To the

tomcat5.conf

file in the

/var/opt/novell/tomcat5/conf

directory, add the

following line:

JAVA_OPTS="${JAVA_OPTS} -DJCECSP_DEBUG=255 -DJCECSP_DEBUGFILE=/var/
opt/novell/tomcat5/logs/nCipher_jcecsp.debug"

5b Restart Tomcat by entering the following command:

/etc/init.d/novell-tomcat5 restart

5c Look for clues in the

nCipher_jcecsp.debug

file.

1.7 Configuring Secure Communication on the
Identity Server

The Identity Server uses the following key pairs for secure communication. In a production
environment, you should exchange the key pairs that are created at installation time with certificates
from a trusted certificate authority.

 Connector: The test-connector key pair is used when you establish SSL communication

between the Identity Server and the browsers and between the Identity Server and the Access
Gateway back-channel communications. It needs to be replaced with a certificate that has a
subject name that matches the DNS name of the Identity Server. This task is part of basic setup.
See “Enabling SSL Communication” in the Novell Access Manager 3.1 SP1 Setup Guide.

 Signing: The test-signing key pair is used by the various protocols to sign authentication

requests, to sign communication with providers on the SOAP back-channel, and to sign Web
Service Provider profiles. For more information on the services that use the signing certificate,
see “Access Manager Services That Use the Signing Certificate” on page 50.

This certificate can be stored in an external HSM keystore. For information on how to use
netHSM to replace and manage this signing certificate, see Section 1.6, “Using netHSM for the

Signing Key Pair,” on page 49.

 Data Encryption: The test-encryption key pair is used to encrypt specific fields or data in the

assertions. For more information on the services that use the encryption certificate, see

Section 1.7.2, “Viewing Services That Use the Encryption Key Pair,” on page 68.

To force the browser connections to the Identity Server to support a specific level of encryption, see

Section 1.8.3, “Forcing 128-Bit Encryption,” on page 72.

66 Novell Access Manager 3.1 SP1 Identity Server Guide

If you are going to use introductions in your federation configuration, you need to set up the
following key pairs:

 Identity provider: The test-provider key pair is used when you configure your Identity Server

to use introductions with other identity providers and have set up a common domain name for
this purpose. It needs to be replaced with a certificate that has a subject name that matches the
DNS name of the common domain. For configuration information, see Section 5.2.1,

“Configuring the General Identity Provider Options,” on page 144.

 Identity consumer: The test-consumer key pair is used when you configure your Identity

Server to use introductions with other service providers and have set up a common domain
name for this purpose. It needs to be replaced with a certificate that has a subject name that
matches the DNS name of the common domain. For configuration information, see

Section 5.2.2, “Configuring the General Identity Consumer Options,” on page 145.

To enable secure communication between the user store and the Identity Server, you can also import
the trusted root certificate of the user store. For configuration information, see Section 2.1.2,

“Configuring the User Store,” on page 77.

This section describes the following tasks:

novdocx (en) 19 February 2010

 Section 1.7.1, “Viewing the Services That Use the Signing Key Pair,” on page 67

 Section 1.7.2, “Viewing Services That Use the Encryption Key Pair,” on page 68

 Section 1.7.3, “Managing the Keys, Certificates, and Trust Stores,” on page 68

1.7.1 Viewing the Services That Use the Signing Key Pair

The following services can be configured to use signing:

 “Protocols” on page 67

 “SOAP Back Channel” on page 67

 “Profiles” on page 68

Protocols

The protocols can be configured to sign authentication requests and responses.

To view your current configuration:

1 In the Administration Console, click Devices > Identity Servers > Edit.

2 In the Identity Provider section, view the setting for the Require Signed Authentication

Requests option. If it is selected, all authentication requests from identity providers are signed.

3 In the Identity Consumer section, view the settings for the Require Signed Assertions and Sign

Authentication Requests options. If these options are selected, assertions and authentication

requests are signed.

SOAP Back Channel

The SOAP back channel is the channel that the protocols use to communicate directly with a
provider. The SOAP back channel is used for artifact resolutions and attribute queries for the
Identity Web Services Framework.

Configuring an Identity Server 67

To view your current configuration for the SOAP back channel:

1 In the Administration Console, click Devices > Identity Servers > Edit.

2 Select the protocol (Liberty, SAML 1.1, or SAML 2.0), then click the name of an identity

provider or service provider.

3 Click Access.

4 View the Security section. If the Message Signing option is selected, signing is enabled for the

SOAP back channel.

Profiles

Any of the Web Service Provider profiles can be enabled for signing by configuring them to use
X.509 for their message-level security mechanism.

To view your current configuration:

1 In the Administration Console, click Devices > Identity Servers > Edit > Liberty > Web S ervic e

Provider.

2 Click the name of a profile, then click Descriptions.

novdocx (en) 19 February 2010

3 Click the Description Name.

4 If either Peer entity = None, Message=X509 or Peer entity = MutualTLS, Message=X509 has

been selected as the security mechanism, signing has been enabled for the profile.

1.7.2 Viewing Services That Use the Encryption Key Pair

All of the Liberty Web Service Provider Profiles allow you to configure them so that the resource
IDs are encrypted. By default, no profile encrypts the IDs.

To view your current configuration:

1 In the Administration Console, click Devices > Identity Servers > Edit > Liberty > Web Service

Provider.

2 Click the name of a profile.

3 If the Have Discovery Encrypt This Service’s Resource IDs option is selected, the encryption

key pair is used to encrypt the resource IDs.

1.7.3 Managing the Keys, Certificates, and Trust Stores

You can view the private keys, CA certificates, and certificate containers associated with the
Identity Server configuration. Primarily, you use the Security page to add and replace CA
certificates as necessary and to perform certificate management tasks, such as adding trusted root
certificates to a trust store.

1 In the Administration Console, click Devices > Identity Servers > Edit > Security.

68 Novell Access Manager 3.1 SP1 Identity Server Guide

2 To view or manage keys and certificates:

2a Click any of the following links:

Encryption: Displays the NIDP-encryption certificate keystore. The encryption
certificate is used to encrypt specific fields or data in the assertions. Click Replace to
replace the encryption certificate.

novdocx (en) 19 February 2010

Signing: Displays the NIDP-signing certificate keystore. The signing certificate is used to
sign the assertion or specific parts of the assertion. Click Replace to replace the signing
certificate.

SSL: (Required) Displays the NIDP-connector keystore. Click this link to access the
keystore and replace the connector certificate.

Provider: Displays the NIDP-provider keystore. Click this link to access the keystore and
replace the provider certificate used by the Identity Server when it is acting as an identity
provider.

Consumer: Displays the NIDP-consumer keystore. Click this link to access the keystore
and replace the consumer certificate used by the Identity Server when it is acting as an
identity consumer (service provider).

For example, when you click the Provider keystore, the following page appears:

Configuring an Identity Server 69

2b To replace a certificate, click Replace, browse to locate the certificate, then click OK.

novdocx (en) 19 February 2010

3 To manage trust stores associated with the Identity Server:

3a Click either of the following links on the Security page:

NIDP Trust Store: This Identity Server trust store contains the trusted root certificates of
all the providers that it trusts. Liberty and SAML 2.0 protocol messages that are
exchanged between identity and service providers often need to be digitally signed. A
provider uses the signing certificate included with the metadata of a trusted provider to
validate signed messages from the trusted provider. The trusted root of the CA that created
the signing certificate for the service provider needs to be in this trust store.

To use SSL for protocol messages to be exchanged between providers, each provider must
trust the SSL certificate authority (CA) of the other provider. You must import the root
certificate chain for the other provider. Failure to do so causes numerous system errors.

OCSP Trust Store: The Identity Server uses this trust store for OCSP certificates. Online
Certificate Status Protocol is a method used for checking the revocation status of a
certificate. To use this feature, you must set up an OCSP server. The Identity Server sends
an OCSP request to the OCSP server to determine if a certain certificate has been revoked.
The OCSP server replies with the revocation status. If this revocation checking protocol is
used, the Identity Server does not cache or store the information in the reply, but sends a
request every time it needs to check the revocation status of a certificate. The OCSP reply
is signed by the OCSP server. To verify that it was signed by the correct OCSP server, the
OCSP server certificate needs to be added to this trust store. The OCSP server certificate
itself is added to the trust store, not the CA certificate.

For example, if you click the NIDP Trust Store, the following page appears:

70 Novell Access Manager 3.1 SP1 Identity Server Guide

3b Specify the server IP address and port.

The auto-import displays the certificate chain, which you can select for import.

novdocx (en) 19 February 2010

3c Click OK, then click Close.

4 Restart Tomcat.

The system prompts you with a dialog box to restart Tomcat. This is necessary whenever
security changes are made to the Identity Server.

For more information about enabling security for a basic Access Manager configuration, see
“Enabling SSL Communication” in the Novell Access Manager 3.1 SP1 Setup Guide.

For additional information about managing certificates, see “Security and Certificate Management”
in the Novell Access Manager 3.1 SP1 Administration Console Guide.

1.8 Security Considerations

By default, all Access Manager components (Identity Server, Access Gateway, SSL VPN, and
J2EE* Agents) trust the certificates signed by the local CA. We recommend that you configure the
Identity Server to use an SSL certificate signed externally, and that you configure the trusted store of
the service provider for each component to trust this new CA. See “Assigning Certificates to Access

Manager Devices” in the Novell Access Manager 3.1 SP1 Administration Console Guide.

Be aware of the following security issues:

 Section 1.8.1, “Federation Options,” on page 71

 Section 1.8.2, “Authentication Contracts,” on page 72

 Section 1.8.3, “Forcing 128-Bit Encryption,” on page 72

1.8.1 Federation Options

When you set up federation between an identity provider and a service provider, you can select
either to exchange assertions with a post method or to exchange artifacts. An artifact is a randomly
generated ID, it contains no sensitive data, and only the intended receiver can use it to retrieve

Configuring an Identity Server 71

assertion data. Assertions might contain the user’s password or other sensitive data, which can make
them less secure than an artifact when the assertion is sent to the browser. It is possible for a virus on
the browser machine to access the memory where the browser decrypts the assertion. If both
providers support artifacts, you should select this method because it is more secure. For more
details, see the Response protocol binding option in Section 5.4.5, “Configuring an Authentication

Request for an Identity Provider,” on page 159.

1.8.2 Authentication Contracts

By default, the Administration Console allows you to select from the following contracts and
options when specifying whether a resource requires an authentication contract:

 None: Allows public access to the resource and does not require authentication contract.

 Name/Password - Basic: Requires that the user enter a name and password that matches an

entry in an LDAP user store. The credentials do not need to be sent over a secure port. This
uses the unprotected BasicClass, which is not recommended for a production environment.

 Name/Password - Form: Requires that the user enter a name and password that matches an

entry in an LDAP user store. The credentials do not need to be sent over a secure port, although
they can be if the user is configured for HTTPS. This contract uses the unprotected
PasswordClass, which is not recommended for a production environment.

 Secure Name/Password - Basic: Requires that the user enter the name and password from a

secure (SSL) connection. This uses the ProtectedBasicClass, which is recommended for a
production environment. If your Web servers are using basic authentication, this contract
provides the credentials for this type of authentication.

novdocx (en) 19 February 2010

 Secure Name/Password - Form: Requires that the user enter the name and password from a

secure (SSL) connection. This uses the ProtectedPasswordClass, which is recommended for a
production environment.

 Any Contract: Allows the user to use any contract defined for the Identity Server

configuration.

If you have set up the Access Manager to require SSL connections among all of its components, you
should delete the Name/Password - Form and the Name/Password - Basic contracts. This removes
them from the list of available contracts when configuring protected resources and prevents them
from being assigned as the contract for a protected resource. If these contracts are assigned, the
user’s password can be sent across the wire in clear text format. At some future date, if your system
needs this type of contract, you can re-create it from the method. To delete these contracts, go to the
Administration Console and click Identity Servers > Servers > Edit > Local > Contracts.

1.8.3 Forcing 128-Bit Encryption

You can force all client communication with the Identity Server to use 128-bit encryption by
modifying the

server.xml

encryption level specified in this file, the user is not allowed to authenticate.

1 At a command prompt, change to the Tomcat configuration directory:

Linux:

Windows:

2 To th e

/var/opt/novell/tomcat5/conf

C:\Program Files\Novell\Tomcat\conf

server.xml

the following line:

file used by Tomcat. If the browser is unable to supported the

file, add the cipher suites you want to support. For 128-bit encryption, add

72 Novell Access Manager 3.1 SP1 Identity Server Guide

ciphers="TLS_RSA_WITH_AES_128_CBC_SHA,TLS_DHE_RSA_WITH_AES_128_CBC_SHA,
TLS_DHE_DSS_WITH_AES_128_CBC_SHA"

This is a comma separated list of the JSSE names for the TLS cipher suites.

IMPORTANT: If you enter a cipher name incorrectly, Tomcat reverts to the default values,
which allow the weak ciphers to be used.

If you want to allow the SSL cipher suites, the following JSSE names can be added to the list:

SSL_RSA_WITH_RC4_128_MD5

SSL_RSA_WITH_RC4_128_SHA

For a complete list of supported cipher suites and their requirements, see The SunJSSE

Provider (http://java.sun.com/javase/6/docs/technotes/guides/security/
SunProviders.html#SunJSSEProvider).

3 To activate the cipher list, restart Tomcat.

Linux: Enter the following command:

/etc/init.d/novell-tomcat5 restart

Windows: Enter the following commands:

novdocx (en) 19 February 2010

net stop Tomcat5

net start Tomcat5

4 (Conditional) If you have multiple Identity Servers in your cluster configuration, repeat these

steps on each Identity Server.

Configuring an Identity Server 73

novdocx (en) 19 February 2010

74 Novell Access Manager 3.1 SP1 Identity Server Guide

2

Configuring Local Authentication

To guard against unauthorized access, Access Manager supports a number of ways for users to
authenticate. These include name/password, RADIUS token-based authentication, and X.509 digital
certificates. You configure authentication at the Identity Server by creating authentication contracts
that the components of Access Manager (such as an Access Gateway) can use to protect a resource.

Figure 2-1 illustrates the components of a contract:

Figure 2-1 Local Authentication

Contracts

novdocx (en) 19 February 2010

2

BA

User Store

 User stores: The user directories to which users authenticate on the back end. You set up your

user store when creating the Identity Server cluster configuration. See Section 2.1,

“Configuring Identity User Stores,” on page 76.

 Classes: The code (a Java class) that implements a particular authentication type (name/

password, RADIUS, and X.509) or means of obtaining credentials. Classes specify how the
Identity Server requests authentication information, and what it should do to validate those
credentials. See Section 2.2, “Creating Authentication Classes,” on page 88.

 Methods: The pairing of an authentication class with one or more user stores, and whether the

method identifies a user. See Section 2.3, “Configuring Authentication Methods,” on page 92.

 Contracts: The basic unit of authentication. Contracts can be local (executed at the server) or

external (satisfied by another Identity Server). Contracts are identified by a unique URI that can
be used by Access Gateways and agents to protect resources. Contracts are comprised of one or
more authentication methods used to uniquely identify a user. You can associate multiple
methods with one contract. See Section 2.4, “Configuring Authentication Contracts,” on

page 94.

This section also explains how to configure authentication when the user store supports password
expiration services, when a request allows any contract to be used for authentication, and when you
want to control authenticating directly to the Identity Server.

Classes

Methods

URI

A

Local External

URI

B

 Section 2.5, “Using a Password Expiration Service,” on page 96

 Section 2.6, “Specifying Authentication Defaults,” on page 98

 Section 2.7, “Managing Direct Access to the Identity Server,” on page 99

Configuring Local Authentication

75

2.1 Configuring Identity User Stores

User stores are LDAP directory servers to which end users authenticate. You must specify an initial
user store when creating an Identity Server configuration. This procedure describes how to add an
additional user store to provide load balancing and failover capability. You use the same pages for
setting up the initial user store, adding a user store, or modifying an existing user store.

 Section 2.1.1, “Using More Than One LDAP User Store,” on page 76

 Section 2.1.2, “Configuring the User Store,” on page 77

 Section 2.1.3, “Configuring an Admin User for the User Store,” on page 80

 Section 2.1.4, “Configuring a User Store for Secrets,” on page 80

2.1.1 Using More Than One LDAP User Store

You can configure the Identity Server to search more than one user store during authentication.

Figure 2-2 illustrates this type of configuration.

Figure 2-2 Multiple LDAP Directories

novdocx (en) 19 February 2010

LDAP User Store (1)

Identity Server

LDAP User Store (2)

Kim
Lynn
KC

Bob
Kelly
Paulo

It is assumed that each LDAP directory contains different users. You should make sure the users
have unique names across all LDAP directories. If both directories contain a user with an identical
name, the name and password information discovered in the search of the first directory is always
used for authentication. You select the user store and specify the search order when configuring the
authentication method.

When users are added to the configuration store, objects are created for Access Manager profiles. If
you delete a user from the LDAP directory, orphaned objects for that user remain in the
configuration store. Ensure that you delete those objects as well.

If you add a secondary Administration Console and you have added replicas to the user store of the
primary Administration Console, ensure that you also add the replicas to the secondary
Administration Console.

76 Novell Access Manager 3.1 SP1 Identity Server Guide

All user stores that you add are included in health checks. If health problems are found, the system
displays the user store on the Health page and in the trace log file.

2.1.2 Configuring the User Store

1 In the Administration Console, click Devices > Identity Servers > Servers > Edit > Local.

2 In the User Stores list, click New.

If you are creating an Identity Server configuration, this is Step 3 of the wizard.

novdocx (en) 19 February 2010

3 Fill in the following fields:

Name: The name of the user store for reference.

Admin Name: The distinguished name of the admin user of the LDAP directory, or a proxy

user with specific LDAP rights to perform searches. Administrator-level rights are required for
setting up a user store. This ensures read/write access to all objects used by Access Manager.
For more information about this user, see Section 2.1.3, “Configuring an Admin User for the

User Store,” on page 80.

Each directory type uses a slightly different format for the DN:

 eDirectory: cn=admin,ou=users,o=novell

Configuring Local Authentication 77

 Active Directory: cn=Administrator,cn=users,dc=domeh,dc=test,dc=com

or cn=john smith,cn=users,dc=domeh,dc=test,dc=com

 Sun ONE: cn=admin,cn=users,dc=novell,dc=com

Admin Password and Confirm Password: Specify the password for the admin user and
confirm it.

Directory Type: The type of LDAP directory. You can select eDirectory, Active Directory, or
Sun ONE. If you have installed an LDAP server plug-in, you can select the custom type that

you have configured it to use. For more information, see LDAP Server Plug-In (http://

developer.novell.com/documentation/nacm31/nacm_enu/data/bfg38fg.html).

TM

If eDirectory

has been configured to use Domain Services for Windows, eDirectory behaves
like Active Directory*. When you configure such a directory to be a user store, its Directory
Type must be set to Active Directory for proper operation.

novdocx (en) 19 February 2010

Install NMAS SAML method: (eDirectory only) Extends the schema on the eDirectory

TM

server and installs an NMAS
a form understood by eDirectory. This method is required if you have installed Novell

®

SecretStore

on the eDirectory server and you are going to use that SecretStore for Access

method. This method converts the Identity Server credentials to

®

Manager secrets. If you select this option, make sure the admin you have configured for the
user store has sufficient rights to extend the schema and add objects to the tree.

Enable Secret Store lock checking: (eDirectory only) Enables Access Manager to prompt
users for a passphrase when secrets are locked.

 If Access Manager is sharing secrets with other applications and these applications are

using the security flag that locks secrets when a user’s password is reset, you need to
enable this option.

 If Access Manager is not sharing secrets with other applications, the secrets it is using are

never locked, and you do not need enable this option.

4 Under LDAP timeout settings, specify the following:

LDAP Operation: Specify how long in seconds a transaction can take before timing out.

Idle Connection: Specify how long in seconds before connections begin closing. If a

connection has been idle for this amount of time, the system creates another connection.

5 To specify a server replica, click New, then fill in the following fields:

For an eDirectory server, you should use a replica of the partition where the users reside.
Ensure that each LDAP server in the cluster has a valid read/write replica. One option is to
create a users partition (a partition that points to the OU containing the user accounts) and
reference this server replica.

Name: The display name for the LDAP directory server. If your LDAP directory is replicated
on multiple servers, use this name to identify a specific replica.

IP Address: The IP address of the LDAP directory server.

Port: The port of the LDAP directory server.

Use secure LDAP connections: Specifies that the LDAP directory server requires secure

(SSL) connections with the Identity Server.

This is the only configuration we recommend for the connection between the Identity Server
and the LDAP server in a production environment. If you use port 389, usernames and
passwords are sent in clear text on the wire.

78 Novell Access Manager 3.1 SP1 Identity Server Guide

This option must be enabled if you use this user store as a Novell SecretStore User Store
Reference in the Credential Profile details. (See Section 10.4, “Configuring Credential Profile

Security and Display Settings,” on page 226.) If you have specified that this user store is a

SecretStore User Store Reference, this option is enabled but not editable.

Connection limit: The maximum number of pooled simultaneous connections allowed to the
LDAP server. Valid values are between 5 and 100.

6 Click Auto import trusted root.

7 Click OK to confirm the import.

8 Select one of the certificates in the list.

You are prompted to choose either a server certificate or a root CA certificate. To trust one
certificate, choose Server Certificate. Choose Root CA Certificate to trust any certificate signed
by that certificate authority.

9 Specify an alias, then click OK.

10 Click OK in the Specify server replica information dialog box.

11 Select the replica, then click Validate to test the connection between the Identity Server and the

replica.

The system displays the result under Validation Status. The system displays a green check
mark if the connection is valid.

novdocx (en) 19 February 2010

12 (Optional) To add additional replicas for the same user store, repeat Step 5 through Step 11.

Adding multiple replicas adds load balancing and failover to the user store. Replicas must be
exact copies of each other.

For load balancing, a hash algorithm is used to map a user to a replica. All requests on behalf of
that user are sent to that replica. Users are moved from their replica to another replica only
when their replica is no longer available.

13 Add a search context.

The search context is used to locate users in the directory when a contract is executed.

 If a user exists outside of the specified search context (object, subtree, one level), the

Identity Server cannot find the user, and the user cannot log in.

 If the search context is too broad, the Identity Server might find more than one match, in

which case the contract fails, and the user cannot log in.

For example, if you allow users to have the same username and these users exist in the
specified search context, these users cannot log in if you are using a simple username and
password contract. The search for users matching this contract would return more than one
match. In this case, you need to create a contract that specifies additional attributes so that the
search returns only one match. For more information on how to create such contracts, see

Section 12.3.1, “Authentication Classes and Duplicate Common Names,” on page 284.

IMPORTANT: For Active Directory, do not set the search context at the root level by using
the Subtree scope. This setting can cause serious performance problems. It is recommended
that you set multiple search contexts, one for each top-level organizational unit.

14 Click Finish.

15 If prompted to restart Tomcat, click OK. Otherwise, update the Identity Server.

16 (Conditional) If you have modified the Identity Server’s certificate, restart the Embedded

Service Provider of any device that has been configured to use this configuration.

Configuring Local Authentication 79

2.1.3 Configuring an Admin User for the User Store

The Identity Server must log in to each configured user store. It searches for users, and when a user
is found, it reads the user’s attributes values. When you configure a user store, you must supply the
distinguished name of the user you want the Identity Server to use for logging in. You can use the
admin user of your user store, or you can create a specialized admin user for the this purpose. When
creating this admin user, you need to grant the following rights:

 The admin user needs rights to browse the tree, so the Identity Server can find the user who is

trying to authenticate. The admin user needs browse rights to object class that defines the users
and read and compare rights to the attributes of that class. When looking for the user, the
Identity Server uses the GUID and naming attributes of the user class.

Directory Object Class GUID Attribute Naming Attribute

eDirectory User guid cn

Active Directory User objectGUID sAMAccountName

Sun ONE inetOrgPerson nsuniqueid uid

novdocx (en) 19 February 2010

 The admin user needs read rights to any attributes used in policies (Role, Form Fill, Identity

Injection, Authorization).

 If a secret store is used in Form Fill policies, the admin user needs write rights to the attributes

storing the secrets.

 If a password management servlet is enabled, the admin user needs read rights to the attributes

controlling grace login limits and remaining grace logins.

 If you enable provisioning with the SAML or Liberty protocols, the admin user needs write

rights to create users in the user store.

If your user store is an eDirectory user store, Access Manager verifies that the admin user has
sufficient rights to browse for users in the specified search contexts.

IMPORTANT: This check is not performed for Active Directory or Sun ONE. If your users cannot
log in, you need to verify that you have given the admin for the user store sufficient rights to the
specified search contexts.

2.1.4 Configuring a User Store for Secrets

Access Manager allows you to securely store user secrets. These secrets can then be used in Form
Fill and Identity Injection policies. Where and how the secrets are stored depends upon your user
store and your configuration:

 “Configuring the Configuration Datastore to Store the Secrets” on page 81.

If you want to do minimal configuration, you can use the configuration datastore on the
Administration Console to store the secrets. To increase the security of the secrets, you should
configure the security options.

 “Configuring an LDAP Directory to Store the Secrets” on page 82.

If you are willing to extend the schema and add an attribute to your user object on the LDAP
directory, you can store the secrets in your LDAP directory.

80 Novell Access Manager 3.1 SP1 Identity Server Guide

 “Configuring an eDirectory User Store to Use SecretStore” on page 84.

If your user store is eDirectory and you have installed Novell SecretStore, you can select to use
the SecretStore on your eDirectory server to store the secrets.

Configuring the Configuration Datastore to Store the Secrets

When you use the configuration datastore of the Administration Console as the secret store, the
nidswsfss attribute of the nidsLibertyUserProfile object is used to store the secrets.

1 In the Administration Console, click Devices > Identity Servers > Servers > Edit > Liberty >

Web Service Providers.

2 Click Credential Profile.

novdocx (en) 19 February 2010

3 Scroll to the Local Storage of Secrets section and configure the following security options:

Encryption Password Hash Key: (Required) Specify the password that you want to use as a
seed to create the encryption algorithm. To increase the security of the secrets, we recommend
that you change the default password to a unique alphanumeric value.

Preferred Encryption Method: Specify the preferred encryption method. Select the method
that complies with your security model:

 Password Based Encryption With MD5 and DES: MD5 is an algorithm that is used to

verify data integrity. Data Encryption Standard (DES) is a widely used method of data
encryption that uses a private key.

Configuring Local Authentication 81

 DES: Data Encryption Standard (DES) is a widely used method of data encryption that

uses a private key. Like other private key cryptographic methods, both the sender and the
receiver must know and use the same private key.

 Triple DES: A variant of DES in which data is encrypted three times with standard DES,

using two different keys.

Extended Schema User Store References: Do not specify a user store reference. When this
option contains no values, the configuration datastore is used to store the secrets.

4 Click OK.

5 On the Identity Servers page, update the Identity Server.

6 To use the secret store to store policy secrets, see “Creating and Managing Shared Secrets” in

the Novell Access Manager 3.1 SP1 Policy Management Guide.

Configuring an LDAP Directory to Store the Secrets

When you use an LDAP directory to store the secrets, you need to enable the user store for the
secrets. You select the LDAP directory, then specify an attribute. The attribute you specify is used to
store an XML document that contains encrypted secret values. This attribute should be a single­valued case ignore string that you have defined and assigned to the user object in the schema.

novdocx (en) 19 February 2010

To use an LDAP directory to store secrets, your network environment must conform to the
following requirements:

 The user class object must contain an attribute that can be used to store the secrets. This

attribute must be a string attribute that is single valued and case ignore.

 The user store must be configured to use secure connections (click Devices > Identity Servers >

Edit > Local > User Stores > [User Store Name]. In the Server replicas section, ensure that the
Port is 636 and that Use SSL is enabled. If they aren’t, click the name of the replica and

reconfigure it.

To configure the LDAP directory:

1 In the Administration Console, click Devices > Identity Servers > Servers > Edit > Liberty >

Web Service Providers.

2 Click Credential Profile.

82 Novell Access Manager 3.1 SP1 Identity Server Guide

novdocx (en) 19 February 2010

3 Scroll to the Local Storage of Secrets section and configure the following options:

Encryption Password Hash Key: (Required) Specifies the password that you want to use as a
seed to create the encryption algorithm. To increase the security of the secrets, we recommend
that you change the default password to a unique alphanumeric value.

Preferred Encryption Method: Specifies the preferred encryption method. Select the method
that complies with your security model:

 Password Based Encryption With MD5 and DES: MD5 is an algorithm that is used to

verify data integrity. Data Encryption Standard (DES) is a widely used method of data
encryption that uses a private key.

 DES: Data Encryption Standard (DES) is a widely used method of data encryption that

uses a private key. Like other private key cryptographic methods, both the sender and the
receiver must know and use the same private key.

 Triple DES: A variant of DES in which data is encrypted three times with standard DES,

using two different keys.

4 To specify where to store secret data, click New under Extended Schema User Store References

and fill in the following:

User Store: Select the user store where you want secret store enabled.

Attribute Name: Specify the LDAP attribute that you have created to store the secrets on the

selected user store.

5 Click OK twice.

Configuring Local Authentication 83

6 On the Identity Servers page, update the Identity Server.

7 To create policies that use the stored secrets, see “Creating and Managing Shared Secrets” in

the Novell Access Manager 3.1 SP1 Policy Management Guide.

For troubleshooting information, see “Troubleshooting the Storing of Secrets” on page 86.

Configuring an eDirectory User Store to Use SecretStore

For Access Manager to use Novell SecretStore, the user store must be eDirectory and Novell
SecretStore must be installed there. When configuring this user store for secrets, Access Manager
extends the eDirectory schema for an NMAS method. This method converts authentication
credentials to a form understood by eDirectory. For example, Access Manager supports smart card
and token authentications, and these authentication credentials must be converted into the username
and password credentials that eDirectory requires. This allows the Identity Server to authenticate as
that user and access the user’s secrets. Without this NMAS method, the Identity Server is denied
access to the user’s secrets.

To use a remote SecretStore, your network environment must conform to the following
requirements:

novdocx (en) 19 February 2010

 The eDirectory server must have Novell SecretStore installed.

 When you configure a user store to use Novell SecretStore, the admin user (see Section 2.1.3,

“Configuring an Admin User for the User Store,” on page 80) you have configured for the user

store must have sufficient rights to extend the schema on the eDirectory server, to install the
SAML NMAS method, and set up the required certificates and objects.

 The user store must be configured to use secure connections (click Access Manager > Identity

Servers > Edit > Local > User Stores > [User Store Name]. In the Server replicas section,

ensure that the Port is 636 and that Use SSL is enabled. If they aren’t, click the name of the
replica and reconfigure it.

 If you have enabled a firewall between the Administration Console and the user store, and

between the Identity Server and the user store, make sure that both LDAP ports (389 and 636)

TM

and the NCP

 If you are going to configure Access Manager to use secrets that are used by other applications,

port (524) are opened.

you need to plan a configuration that allows the user to unlock a locked SecretStore. See

“Determining a Strategy for Unlocking the SecretStore” on page 86.

To configure the user store:

1 In the Administration Console, click Devices > Identity Servers > Servers > Edit > Liberty >

Web Service Providers.

2 Click Credential Profile.

84 Novell Access Manager 3.1 SP1 Identity Server Guide

novdocx (en) 19 February 2010

3 Scroll to the Remote Storage of Secrets section.

4 Click New under Novell Secret Store User Store References.

This adds a reference to a user store where SecretStore has been installed.

5 Click the user store that you configured for SecretStore.

6 Click OK twice.

7 On the Identity Servers page, update the Identity Server.

8 Continue with one of the following:

 If other applications are using the secret store, you need to determine whether Access

Manager users need the option to unlock the secret store. See “Determining a Strategy for

Unlocking the SecretStore” on page 86.

 To create policies that use the stored secrets, see “Creating and Managing Shared Secrets”

in the Novell Access Manager 3.1 SP1 Policy Management Guide.

 For troubleshooting information, see “Troubleshooting the Storing of Secrets” on page 86.

Configuring Local Authentication 85

Determining a Strategy for Unlocking the SecretStore

When an administrator resets a user's password, secrets written to the Novell SecretStore with an
enhanced security flag become locked. The Identity Server does not write the secrets that it creates
with this flag, but other applications might:

 If Access Manager is not sharing secrets with other applications, the secrets it is using are never

locked, and you do not need to configure Access Manager to unlock secrets.

 If Access Manager is sharing secrets with other applications and these application are using the

security flag that locks secrets when a user’s password is reset, you need to configure Access
Manager so that users can unlock their secrets.

If you want users to receive a prompt for a passphrase when secrets are locked, complete the
following configuration steps:

1 Require all users to set up a passphrase (also called the Master Password).

Access Manager uses the SecretStore Master Password as the pass phrase to unlock the secrets.
If the user has not set a passphrase before the SecretStore is locked, this feature of Access
Manager cannot unlock the SecretStore. If it is necessary to unlock the SecretStore by using the
user’s prior password, another tool must be used. See your SecretStore documentation.

novdocx (en) 19 February 2010

2 Configure the Identity Server to perform the check:

2a In the Administration Console, click Devices > Identity Servers > Edit > Local > [User

Store Name].

2b Select the Enable Secret Store lock checking option.

2c Click OK twice, then update the Identity Server.

3 Make sure Web Services Framework is enabled:

3a In the Administration Console, click Devices > Identity Servers > Edit > Liberty > Web

Services Framework.

3b In the Framework General Settings section, make sure that Enable Framework is selected.

3c Click OK. If you made any changes, update the Identity Server.

4 Continue with “Creating and Managing Shared Secrets” in the Novell Access Manager 3.1 SP1

Policy Management Guide.

When the SecretStore is locked and the users log in, the users are first prompted for their login
credentials, then prompted for the passphrase that is used to unlock the SecretStore.

Troubleshooting the Storing of Secrets

 “Secrets Aren’t Stored in Novell SecretStore” on page 86

 “Users Are Receiving Invalid Credential Messages” on page 88

 “Secrets Aren’t Stored in the LDAP Directory” on page 88

Secrets Aren’t Stored in Novell SecretStore

When you use Novell SecretStore to store the secrets, the schema on the eDirectory server must be
extended, and specific SAML objects and certificates must be created.

To verify that the schema was extended and the objects were created on the eDirectory server:

1 Open an LDAP browser and connect to the eDirectory server.

86 Novell Access Manager 3.1 SP1 Identity Server Guide

2 Browse to the Security container.

A

3 Look for objects similar to the following:

eDirectory Tree

Security

novdocx (en) 19 February 2010

uthorizedLogin Methods

SAML Assertion

<SAML_Affiliate_Object>

<AffiliateObjectName> Trusted Root

Certificates

authsamlCertContainerDN
authsamlTrustedCertDN
authsamlValidAfter
authsamlValidBefore

If the schema has been extended correctly, you can find a SAML Assertion object in the
Authorized Login Methods container. The SAML_Assertion object contains an alphanumeric
generated name for a SAML affiliate object. This object has four attributes.

The SAML affiliate object name is used to generate another container in the Security container.
This new container is the <AffiliateObjectName> Trusted Root container that contains public
key signing certificate.

4 Complete one of the following:

 If these objects do not exist, verify the following, then continue with Step 5:

 The admin user for the user store has sufficient rights to extend the schema and add

these objects to the Security container.

 Any configured firewalls must allow NCP and LDAP traffic for the Administration

Console, the Identity Server, and the LDAP user store.

 If the objects exist, check for time synchronization problems. For more information, see

“Users Are Receiving Invalid Credential Messages” on page 88.

5 In the Administration Console, modify the secret store configuration so that it is resent to the

user store:

5a Click Devices > Identity Servers > Servers > Edit > Liberty > Web Service Providers >

Credential Profile.

5b In the Remote Storage of Secrets section, remove the user store, then add it again.

5c Click OK.

6 On the Identity Servers page, update the Identity Server.

Configuring Local Authentication 87

Users Are Receiving Invalid Credential Messages

The <SAML_Affiliate_Object>.SAML-Assertion.AuthorizedLoginMethods.Security object
contains two attributes that determine how long credentials are valid. If your Identity Server and
eDirectory server are not time synchronized, the credentials can become invalid before a user has
time to use them.

Either make sure that the time of your Identity Server and eDirectory server are synchronized, or
increase the value of the authsamlValidAfter and authsamlValidBefore attributes of the SAML
affiliate object.

Secrets Aren’t Stored in the LDAP Directory

1 Open an LDAP browser and connect to the eDirectory server.

2 Browse to the user object.

3 Verify that the user object contains the LDAP attribute that you have specified as the attribute

to store the secrets.

4 If the attribute exists, browse to the schema and verify that the attribute has the following

characteristics:

 Single valued

novdocx (en) 19 February 2010

 Case ignore

 String

2.2 Creating Authentication Classes

Authentication classes let you define ways of obtaining end user credentials.You specify the code
(Java class) and properties to be executed to implement a particular authentication type.

Several authentication classes are included with Access Manager to provide a variety of ways to
authenticate end users. Custom authentication classes provided by other vendors can also be
configured to run in the system.

 Section 2.2.1, “Creating Basic or Form-Based Authentication Classes,” on page 88

 Section 3.1, “Configuring for RADIUS Authentication,” on page 105

 Section 3.2, “Configuring Mutual SSL (X.509) Authentication,” on page 106

 Section 3.3, “Creating an ORed Credential Class,” on page 111

Some classes require additional configuration to enable their use for authentication. See the
following sections:

 Section 3.4, “Configuring for Kerberos Authentication,” on page 113

 Section 3.5, “Configuring Access Manager for NESCM,” on page 125

2.2.1 Creating Basic or Form-Based Authentication Classes

1 In the Administration Console, click Devices > Identity Server > Servers > Edit > Local >

Classes.

88 Novell Access Manager 3.1 SP1 Identity Server Guide

The following classes are predefined for Access Manager:

Name/Password - Basic: Basic authentication over HTTP using a standard login pop-up page
provided by the Web browser.

Name/Password - Form: Form-based authentication over HTTP or HTTPS.

Secure Name/Password - Basic: Basic authentication over HTTPS using a standard login

page provided by the Web browser.

Secure Name/Password - Form: Form-based authentication over HTTPS.

2 Click New to launch the Create Authentication Class Wizard.

novdocx (en) 19 February 2010

3 Specify a display name, then select a class from the Java class drop-down menu.

The following classes are recommended only for testing purposes:

BasicClass: Uses basic HTTP authentication.

PasswordClass: Passes the user name and password over HTTP in readable text, and uses a

form-based login to collect the name and password.

RadiusClass: RADIUS enables communication between remote access servers and a central
server. For a production environment, use ProtectedRadiusClass. See Section 3.1, “Configuring

for RADIUS Authentication,” on page 105 for configuration steps.

For a production environment, select one of the following protected classes:

X509Class: See Section 3.2, “Configuring Mutual SSL (X.509) Authentication,” on page 106.

ProtectedBasicClass: The BasicClass, protected by HTTPS.

ProtectedPasswordClass: The PasswordClass, protected by HTTPS (form-based).

ProtectedRadiusClass: The RadiusClass, protected by HTTPS. See Section 3.1, “Configuring

for RADIUS Authentication,” on page 105 for configuration steps.

NMASAuthClass: The authentication class used for Novell Modular Authentication Services
(NMAS), which uses fingerprint and other technology as a means to authenticate a user. For
instructions on using the NMAS NESCM method, see Section 3.5, “Configuring Access

Manager for NESCM,” on page 125.

Configuring Local Authentication 89

KerberosClass: The authentication class used for using Kerberos* for Active Directory and
Identity Server authentication. See Section 3.4, “Configuring for Kerberos Authentication,” on

page 113 for configuration steps.

NPOrRadiusOrX509Class: The authentication class that allows the creation of a contract
from which the user can select an authentication method: name/password, RADIUS, or X.509.
For configuration information, see Section 3.3, “Creating an ORed Credential Class,” on

page 111.

Other: Used for third-party authentication classes or if you have written your own Java class.
For information on how to write your own class, see Novell Access Manager Developer Tools

and Examples (http://developer.novell.com/wiki/index.php/
Novell_Access_Manager_Developer_Tools_and_Examples).

To download an authentication class that retrieves the user’s password and injects it into the
user’s credentials when the user authenticates using a non-password method such as X509,
RADIUS, smart card, or Kerberos, see Access Management Authentication Class Extension to

Retrieve Password for Single Sign-on (http://www.novell.com/communities/node/4556). Such

a class allows you to enable single sign-on with Identity Injection and Form Fill policies that
require the user’s password.

4 Click Next to configure the properties for each class. Click New, then enter a name and value.

The names and values you enter are case sensitive. See Section 2.2.2, “Specifying Common

Class Properties,” on page 90 for the properties that are used by the Access Manager installed

classes.

novdocx (en) 19 February 2010

5 Click Finish.

6 Continue with Section 2.3, “Configuring Authentication Methods,” on page 92.

To use an authentication class, the class must have one or more associated methods.

2.2.2 Specifying Common Class Properties

The following properties can be used by basic and password classes:

 “Query Property” on page 90

 “JSP Property” on page 91

 “MainJSP Property” on page 92

These properties can also be specified on a method derived from the class. If you are going to create
multiple methods from the same class, consider the following conditions:

 If you want the methods to share the same properties, you can save configuration steps by

defining the properties on the class.

 If you want the methods to use different values for the properties such as one method

specifying one custom login page and another method specifying a different custom login page,
then you should specify the properties on the method.

Query Property

Normally, the Identity Server uses the username to find a user in the user store. You can change this
behavior by using the Query property. This property determines the username value for
authentication. The default Query string prompts the users for the value of the CN attribute. You can
modify this by requesting a different attribute in the LDAP query.

90 Novell Access Manager 3.1 SP1 Identity Server Guide

The Query property can be used by the following classes or methods derived from these classes:

 BasicClass

 PasswordClass

 ProtectedBasicClass

 ProtectedPasswordClass

When you specify a Query property, you must also modify the login page to prompt the user for the
correct information. If you want users to enter their email address instead of the username, you need
to modify the login form to prompt the user for an email address. If you want to prompt the users for
their username and their email address, you need to add the email prompt to the login page. The JSP

Property allows you to specify a custom login page. For information on creating a custom login

page, see Section 1.3, “Customizing the Identity Server Login Page,” on page 30.

For example, to query for the user’s UID attribute to use for the username, you would specify the
following query:

Property Name: Query

novdocx (en) 19 February 2010

Property Value:

(objectclass=person)(uid=%Ecom_User_ID%)

The values are case sensitive. The name of the property must be Query with an initial capital. The

%Ecom_User_ID%

variable is used in the default

login.jsp

for the username in the four classes that
support the Query property. The variable is replaced with the value the user enters for their
username, and the LDAP query is sent to the user store to see if the user’s attribute value matches
the entered value. You can specify any attribute for the Query that is defined in your user store for
the object class of person and that is used to identify the user.

The Query you define for the BasicClass and the ProtectedBasicClass needs to use an attribute that
your users define as their username. The PasswordClass and the ProtectedPasswordClass do not
have this requirement. They also support the JSP property which allows you to specify a custom

login.jsp

and have it prompt for other attributes that can be used for login.

For example, you can define the following Query to prompt the users for their email address. This is
in addition to their username.

Property Name: Query

Property Value:

(&(objectclass=person)(email=%EMail Value%))

The %EMail Value% must match the variable in the custom login page that is filled in when the
users enter their credentials. The objectclass of person must be a valid object class in the LDAP user
store. The email attribute must be a valid attribute of the person class.

JSP Property

The JSP property allows you to specify a custom login page. This property can be used with the
following classes or methods derived from these classes:

 PasswordClass

 ProtectedPasswordClass

The Property Name is JSP and the Property Value is the filename of the login page you customized

.jsp

without the

extension of the file. The Property Value cannot contain

nidp

in its name.

Configuring Local Authentication 91

novdocx (en) 19 February 2010

For example, if you created a custom file named

email_login.jsp,

you would specify the
following values. The values are case sensitive. The Property Name needs to be entered as all
capitals.

Property Name: JSP

Property Value:

email_login

If your custom login page is customizing the login.jsp page so that different prompts appear, you do
not need to also configure the MainJSP property. However, if your custom login page is a modified
version of the nidp.jsp page or has been designed to replace the nidp.jsp page, then you must also
configure the MainJSP Property.

If you use two methods to create a contract, the JSP property must be set to the same value on both
or set on only one. When it is set on only one method, the value is applied to both.

For information on how to create a custom login page, see Section 1.3, “Customizing the Identity

Server Login Page,” on page 30.

MainJSP Property

When the MainJSP property is set to true, it indicates that you want to use the page specified in the
JSP property for the login page. When this property is set to false, which is the default value, the

nidp.jsp

is used for the login page. If you use two methods to create a contract, this property must
be set to the same value on both or set on only one. When it is set on only one method, the value is
applied to both.

Property Name: MainJSP

true

Property Value:

For information on how to create a custom login page, see Section 1.3, “Customizing the Identity

Server Login Page,” on page 30.

2.3 Configuring Authentication Methods

Authentication methods let you associate authentication classes with user stores. You use a
particular authentication class to obtain credentials about an entity, and then validate those
credentials against a list of user stores.

After the system locates the entity in a particular user store, no further checking occurs, even if the
credentials fail to validate the entity. Typically, the entity being authenticated is a user, and the
definition of an authentication method specifies whether this is the case. You can alter the behavior
of an authentication class by specifying properties (name/value pairs) that override those of the
authentication class.

To configure a method for an authentication class:

1 In the Administration Console, click Devices > Identity Servers > Servers > Edit > Local >

Methods.

92 Novell Access Manager 3.1 SP1 Identity Server Guide

2 Click one of the predefined authentication methods, or click New to create one.

novdocx (en) 19 February 2010

3 Fill in the following fields:

Display Name: The name to be used to refer to the new method.

Class: The authentication class to use for this method. See Section 2.2, “Creating

Authentication Classes,” on page 88.

Identifies User: Specifies whether this authentication method should be used to identify the
user. Usually, you should enable this option. When configuring multiple methods for a contract,
you might need to disable this option for some methods.

If you enable this option on two or more methods in a contract, these methods need to identify
the same user in the same user store.

If you enable this option on just one method in the contract, that method identifies the user
when the authentication method succeeds. The other methods in the contract must succeed, but
might not authenticated the user. For example, the method that identifies the user could require
a name and a password for authentication, and the other method in the contract could prompt
for a certificate that identifies the user’s computer.

4 Add user stores to search.

You can select from the list of all the user stores you have set up. If you have several user
stores, the system searches through them based on the order specified here. If a user store is not
moved to the User stores list, users in that user store cannot use this method for authentication.

<Default User Store>: The default user store in your system. See Section 2.6, “Specifying

Authentication Defaults,” on page 98.

5 (Optional) Under Properties, click New, then fill in the following fields:

Configuring Local Authentication 93

Property Name: The name of the property to be set. This value is case sensitive and specific to
an authentication class. The same properties that can be set on an authentication class can be set
on the method. For a list, see Step 4 in Section 2.2.1, “Creating Basic or Form-Based

Authentication Classes,” on page 88.

You can use the method properties to override the property settings specified on the
authentication class. For example, you might want to use the authentication class for multiple
companies, but use a slightly different login page that is customized with the company’s logo.
You can use the same authentication class, create a different method for each company, and use
the filename property to specify the appropriate login page for each company.

The Radius classes have the following additional properties that can be set on the method:

 RADIUS_LOOKUP_ATTR: Defines an LDAP attribute whose value is read and used as

the ID is passed to the RADIUS server. If not specified, the user name entered is used.

 NAS_IP_ADDRESS: Specifies an IP address used as a RADIUS attribute. You might

use this property for situations in which service providers are using a cluster of small
network access servers (NASs). The value you enter is sent to the RADIUS server.

Property Value: The values associated with the Property Name field.

6 Click Finish.

7 Continue with Section 2.4, “Configuring Authentication Contracts,” on page 94.

novdocx (en) 19 February 2010

To use a method for authenticating a user, each method must have an associated contract.
Contracts are assigned to resources, and it is access to a resource that triggers the authentication
process. If the user has already supplied the required credentials for the contract, the user is not
prompted for them again.

2.4 Configuring Authentication Contracts

Authentication contracts define how authentication occurs. An Identity Server configuration might
have several authentication contracts available, such as name/password or X.509, which is used for
mutual SSL authentication between the Identity Server and the Access Gateway. Resources at an
Access Gateway or agent are protected by authentication contracts.

NOTE: You cannot delete a contract if it is in use by an Access Gateway or J2EE agent.

Contracts are executed by the identity provider when authenticating a user. A URI uniquely
identifies each contract, and you can assign authentication methods to each contract. A single
contract can be specified for local logins.

1 In the Administration Console, click Devices > Identity Servers > Servers > Edit > Local >

Contracts

2 Click New.

94 Novell Access Manager 3.1 SP1 Identity Server Guide

novdocx (en) 19 February 2010

3 Fill in the following fields:

Display name: Specifies the name of the authentication contract.

URI: Specifies a value that uniquely identifies the contract from all other contracts. For

example, as an identity provider, you might want to publish the details of a contract. In this
case, you can use a URL so that the link resolves to a page. No spaces can exist in the URI
field.

Password expiration servlet: Specifies a URL to a page where the user can change his or her
password. This applies only to eDirectory servers when the password is expired or within the
grace login period. You must use eDirectory to change the number of grace logins.

For more information about how use this type of servlet, see Section 2.5, “Using a Password

Expiration Service,” on page 96.

Allow User Interaction: If you specify a password expiration servlet, you can enable this
option, which allows the users to decide whether to go to the servlet and change their
passwords or to skip the servlet. If you always want to force the users to go the servlet to
change their passwords, do not enable this option.

Authentication Level: A number you can assign to this authentication contract to specify its
security level or rank. You use this setting to preserve authentication contracts of a higher
security level. When you enable the Satisfiable by a contract of equal or higher level option on
this page, the system uses this value as a reference.

For example, you might create a name/password authentication contract and assign it to level
one. You might also create an X.509 authentication contract and assign it to level two. If a user
supplies the credentials for the X.509 level-two contract, the system does not require the
credentials to satisfy the name/password level-one authentication contract.

Satisfiable by a contract of equal or higher level: Allows the system to satisfy this
authentication contract if a user has logged in using another contract of an equal or higher
authentication level, as specified in the Authentication Level field of an authentication contract.

Configuring Local Authentication 95

Satisfiable by External Provider: Allows this contract to be selected when configuring an
identity provider for Liberty or SAML 2.0. When configuring the authentication request, you
can select a contract that has this option enabled and require the identity provider to use this
contract in order for authentication to succeed.

Methods and Available Methods: Specifies the authentication method to use for the contract.
You can specify the order in which the methods are executed for login; however, this is not a
graded list, so all the methods you specify are required. Available methods are the
authentication methods you have set up.

If you add more than one X.509 method, only the first one is used and it is automatically moved
to the top of the list.

When choosing a secure method, such as Secure Name/Password, ensure that you have enabled
security for the Identity Server configuration by setting the protocol to HTTPS. See
“Configuring Secure Communication on the Identity Server” in the Novell Access Manager 3.1

SP1 Setup Guide.

4 Click Next.

5 Configure a card for the contract by filling in the following:

ID: (Optional) Specify an alphanumeric value that identifies the card. If you need to reference
this card outside of the Administration Console, you need to specify a value here. If you do not
assign a value, the Identity Server creates one for its internal use.

Text: Specify the text that is displayed on the card to the user.

Image: Specify the image to be displayed on the card. Select the image from the drop down

list. To add an image to the list, click Select local image.

Show Card: Determine whether the card is shown to the user, which allows the user to select
and use the card for authentication. If this option is not selected, the card is only used when a
service provider makes a request for the card.

6 Click Finish, then OK.

7 Update the Identity Server and any devices that use the Identity Server configuration.

novdocx (en) 19 February 2010

8 To use this contract, you must configure Access Manager to use it:

 You can assign it as the default contract for the Identity Server. See Section 2.6,

“Specifying Authentication Defaults,” on page 98

 You can configure a protected resource to use it. See “Configuring Protected Resources”

in the Novell Access Manager 3.1 SP1 Access Gateway Guide.

2.5 Using a Password Expiration Service

Access Manager works with any password management service that works with your user store. For
an implementation example, see Configuring Access Manager for UserApp and SAML (http://

www.novell.com/coolsolutions/appnote/19981.html).

As you configure the service, be aware of the following configuration options:

 Section 2.5.1, “URL Parameters,” on page 97

 Section 2.5.2, “Forcing Authentication after the Password Has Changed,” on page 97

 Section 2.5.3, “Grace Logins,” on page 98

 Section 2.5.4, “Federated Accounts,” on page 98

96 Novell Access Manager 3.1 SP1 Identity Server Guide

2.5.1 URL Parameters

When you are defining the URL for the password service on the Contracts page, the following
optional tags can be used in the parameter definitions of the URL. You need to use parameter names
that are understood by the service you have selected to use. The Identity Server does not need to
understand these parameters, but the password expiration service needs to understand them.

The table below lists a few common ones. Your service might or might not use these, and might
require others.

Parameter Description

novdocx (en) 19 February 2010

<USERID>

<STOREID>

<RETURN_URL>

action=expire

Provides the DN of the user with a password that is expired or expiring.

Provides the name of the user store that authenticated the user before
redirecting the user to the password expiration service.

Provides the URL at the Identity Server to which the user can be redirected
after the password service completes.

Causes the password expiration service to behave as though the user’s
password policy is set to allow the user to reset the password even though the
user’s policy might be set to show the user a hint. The user sees the page to
create a new password rather than shown a hint for an existing password.

For example:

https://someservice.com/path/password?user=<USERID>&store=<STOREID>
&returl=<RETURN_URL>&action=expire

NOTE: If you copy and paste this text, make sure you remove the white space between
and

&returl

.

<STOREID>

The Identity Server fills in these values, which results in the following URL:

https://someservice.com/path/password?user=joe.novell&store=userstore1&returl=https://
myidp.com/nidp/idff/sso&action=expire

2.5.2 Forcing Authentication after the Password Has Changed

The password service can also include parameters on the return URL sent to the Identity Server. The
Identity Server understands the following parameter:

Parameter Description

forceAuth=TRUE When the user is returned to the Identity Server, this parameter forces the

user to authenticate with the new password. This eliminates the possibility of
an old password being used in an Identity Injection policy.

The following example sends this parameter with
base URL of the Identity Server.

<form id="externalForm" action='https://testnidp.novell.com:8443/nidp/idff/
sso?sid=0&id=117&forceAuth=TRUE' method="post">

https://testnidp.novell.com:8443

Configuring Local Authentication 97

as the

When the user is redirected to the password management service URL because of an expired
password, the POST data in that redirect contains the
used for the Identity Server return URL.

sid=<>

and

id=<>

values as part of the value

2.5.3 Grace Logins

If you specify a password service and do not specify a value for the number of grace logins in
eDirectory, the contract redirects to the password management service only when the grace login
count has reached 0 and the password has expired.

The Identity Server needs to read the value of the grace login attribute in order to properly redirect to
the password management servlet. If restricting grace logins is not important to your security model,
enable grace logins and set the maximum to 9999 (the equivalent of infinite in most environments).
For more information, see TID 3465171 (http://www.novell.com/support/

search.do?cmd=displayKC&docType=kc&externalId=3465171&sliceId=SAL_Public&dialogID=5
5170068&stateId=0%200%2055168646).

2.5.4 Federated Accounts

novdocx (en) 19 February 2010

A user’s password does not expire and grace logins are not decremented when you have the
following setup:

 The Identity Server is configured to act as a service provider

 User identification is configured to allow federation

 Federation is set up with SAML 2.0, Liberty, WS Federation, or CardSpace protocols

The password expiration service is not called because the user is not using a password for
authentication. The service can only be called when the user’s account is defederated. After the user
has defederated the account, the next time the user logs in, a password is required and the service is
called.

2.6 Specifying Authentication Defaults

You can specify default values for how the system processes user stores and authentication
contracts. The default contract is executed when users access the system without a specified
contract, and when the Access Gateway is configured to use any authentication.

Additional default contracts can be specified for each authentication type that might be required by a
service provider. These contracts are executed when a request for a specific authentication type
comes from a service provider.

1 In the Administration Console, click Devices > Identity Servers > Servers > Edit > Local >

Defaults

98 Novell Access Manager 3.1 SP1 Identity Server Guide

2 Configure the following fields as necessary:

User Store: Specifies the default user store for local authentication. If you selected <Default
User Store> when configuring an authentication method, the system uses the user store you

specify here.

Authentication Contract: Specifies the default authentication contract to be used when users
access the Identity Server directly or a protected resource is configured to use Any Contract. If
you create a new contract and specify it as the default one, ensure that you update the Access
Gateway configuration if it has protected resources configured to use Any Contract. See
“Configuring Protected Resources” in the Novell Access Manager 3.1 SP1 Access Gateway

Guide.

Authentication Type: Specifies the default authentication contracts to be used for each
authentication type. When a service provider requests a specific authentication type, rather than
a contract, the identity provider uses the authentication contract specified here for the requested
authentication type.

You must create the authentication contracts prior to assigning them as defaults. (See

“Configuring Authentication Contracts” on page 94.)

novdocx (en) 19 February 2010

3 Click OK.

4 Update the Identity Server.

2.7 Managing Direct Access to the Identity
Server

Users usually log into the Identity Server when they request access to a Web resource. They are
redirected by the Access Gateway from the resource to the Identity Server to provide the required
credentials for the resource. After they are authenticated, they are not prompted for credentials
again, unless a resource requires credentials that they haven’t already supplied.

However, users can log directly into the Identity Server and access the User Portal, or they can
access information about available Web Services Description Language (WSDL) services. This
section describes how to manage access to these pages.

 Section 2.7.1, “Logging In to the User Portal,” on page 100

 Section 2.7.2, “Specifying a Target,” on page 101

 Section 2.7.3, “Blocking Access to the WSDL Services Page,” on page 101

Configuring Local Authentication 99

2.7.1 Logging In to the User Portal

Users can log directly in to the Identity Server when they enter the Base URL of the Identity Server
in their browsers. For example, if your base URL is http://doc.provo.novell.com:8080/nidp, entering
this URL prompts the user to authenticate with the credentials required for the default contract.

Figure 2-3 User Portal

novdocx (en) 19 February 2010

When users log directly into the Identity Server, the users need to use the default card for
authentication. This is the card that appears in the top left frame, and the credentials it requires are
displayed in the top right frame.

On a newly installed system, cards for all the authentication contracts that are installed with the
system are displayed. To avoid confusing your users, you need to disable the Show Card option for
the contracts you do not want your users to use. In the Administration Console, click Devices >
Identity Servers > Edit > Local > Contracts > [Name of Contract] > Authentication Card.

Also, make sure you modify the default contract to match a card that is displayed. In the
Administration Console, click Devices > Identity Servers > Edit > Local > Defaults.

If you display multiple cards, users can use different credentials to authenticate multiple times by
selecting another authentication card and entering the required credentials. This is only useful if the
credentials grant the user different roles or authorize access to different resources.

If you have configured the Identity Server to be a service provider and have established a trusted
relationship with one or more identity providers, the cards of these trusted identity providers appear
in the Authentication Cards section. Your users can use the identity provider’s authentication card to
federate their account at the identity provider with their account at the service provider. When they
federate an account, they are telling the service provider to trust the authentication established at the
identity provider. This enables single sign-on between the providers. The card can also be used to
defederate the accounts. On the authentication card, click Card Options, then select Defederate.

If you have configured the Identity Server to be an identity provider for service providers, a
Federation page is accessible after log in. From this page, users can federate and defederate their
accounts with trusted service providers.

100 Novell Access Manager 3.1 SP1 Identity Server Guide