Access Manager 4.

5
Administration Guide
April 2019
 Legal Notice
For information about legal notices, trademarks, disclaimers, warranties, export and other use restrictions, U.S.
Government rights, patent policy, and FIPS compliance, see https://www.microfocus.com/about/legal/.

© Copyright 2019 Micro Focus or one of its affiliates.

2
Contents

About this Book and the Library 23

Part I Configuring Access Manager 25

1 Configuring Administration Console 27

1.1 Configuring the Default View . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
1.1.1 Changing the View . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
1.1.2 Setting a Permanent Default View . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
1.2 Managing Administration Console Session Timeout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
1.3 Managing Administrators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
1.3.1 Creating Multiple Admin Accounts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
1.3.2 Managing Policy View Administrators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
1.3.3 Managing Delegated Administrators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
1.3.4 Changing Administrator’s Password . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
1.4 Changing the IP Address of Access Manager Devices. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
1.4.1 Changing the IP Address of Administration Console . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
1.4.2 Changing the IP Address of Identity Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
1.4.3 Changing the IP Address of Access Gateway Appliance . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
1.4.4 Changing the IP Address of Access Gateway Service. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
1.4.5 Changing the IP Address of Audit Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
1.5 Mapping the Private IP Address to Public IP Address . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
1.5.1 Creating a New NAT IP Address Mapping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
1.5.2 Removing a NAT IP Address Mapping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
1.5.3 Viewing the NAT IP Address Mapping. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
1.5.4 Editing a NAT IP Address Mapping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42

2 Setting Up a Basic Access Manager Configuration 43

2.1 Prerequisites for a Basic Access Manager Setup. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
2.2 Configuring Identity Servers Clusters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
2.2.1 Configuration Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
2.2.2 Prerequisites for Configuring an Identity Servers Cluster . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
2.2.3 Managing a Cluster of Identity Servers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
2.3 Configuring Identity Server Shared Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
2.3.1 Configuring Attribute Sets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
2.3.2 Editing Attribute Sets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
2.3.3 Adding Custom Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
2.3.4 User Attribute Retrieval and Transformation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
2.3.5 Adding Authentication Card Images . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
2.3.6 Creating an Image Set . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
2.3.7 Metadata Repositories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
2.3.8 Configuring User Matching Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
2.3.9 Configuring Advanced Authentication Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
2.3.10 Configuring Self Service Password Reset Server Details in Identity Server . . . . . . . . . . . . 104
2.4 Configuring Access Gateway . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106
2.4.1 Configuring a Reverse Proxy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106

Contents 3
 2.4.2 Configuring a Public Protected Resource . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108
2.4.3 Configuring Access Gateway for Authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
2.4.4 Setting Up Policies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111
2.5 Configuring Access Gateways Clusters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
2.5.1 Prerequisites for Configuring an Access Gateways Cluster . . . . . . . . . . . . . . . . . . . . . . . . . 114
2.5.2 Designing the Membership Type for a Cluster . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114
2.5.3 Configuring a Cluster . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
2.5.4 Managing Access Gateway Cluster Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116
2.6 Protecting Web Resources Through Access Gateway . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120
2.6.1 Configuration Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120
2.6.2 WebSocket Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122
2.6.3 Managing Reverse Proxies and Authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125
2.6.4 Configuring Web Servers of a Proxy Service. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132
2.6.5 Configuring Protected Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134
2.6.6 Configuring HTML Rewriting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146
2.6.7 Configuring Connection and Session Limits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165
2.6.8 Protecting Multiple Resources. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170
2.7 Configuring Trusted Providers for Single Sign-On . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184
2.7.1 Understanding the Trust Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184
2.7.2 Configuring General Provider Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187
2.7.3 Managing Trusted Providers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191
2.7.4 Modifying a Trusted Provider . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197
2.7.5 Communication Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197
2.7.6 Selecting Attributes for a Trusted Provider. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198
2.7.7 Managing Metadata . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200
2.7.8 Configuring an Authentication Response for a Service Provider . . . . . . . . . . . . . . . . . . . . 205
2.7.9 Routing to an External Identity Provider Automatically . . . . . . . . . . . . . . . . . . . . . . . . . . . 205
2.7.10 Using the Intersite Transfer Service. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205
2.8 Configuring Single Sign-On to Specific Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216
2.8.1 Configuring SSO to SharePoint Server. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217
2.8.2 Configuring a Protected Resource for Outlook Web Access . . . . . . . . . . . . . . . . . . . . . . . . 227
2.8.3 Configuring a Protected Resource for a Novell Vibe 3.3 Server . . . . . . . . . . . . . . . . . . . . . 230
2.8.4 Protecting Kerberized Resources with Kerberos Constrained Delegation . . . . . . . . . . . . 235
2.8.5 Configuring Access to the Filr Site through Access Manager . . . . . . . . . . . . . . . . . . . . . . . 239
2.9 Configuring a Protected Identity Server Through Access Gateways . . . . . . . . . . . . . . . . . . . . . . . . . 239
2.10 Managing Access to User Portal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246
2.10.1 Logging in to the Default User Portal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246
2.10.2 Logging in with the Legacy Customized Portal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246
2.10.3 Logging in to the User Portal from a Web Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247
2.10.4 Managing Authentication Cards . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247
2.10.5 Specifying a Target . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 248
2.10.6 Blocking Access to the User Portal Page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249
2.10.7 Blocking Access to the WSDL Services Page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249
2.11 Sample Configuration for Protecting an Application Through Access Manager. . . . . . . . . . . . . . . . 251
2.11.1 Installation Overview and Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252
2.11.2 Setting Up the Web Server. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254
2.11.3 Configuring Public Access to Digital Airlines. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256
2.11.4 Implementing Access Restrictions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 259

3 Setting Up an Advanced Access Manager Configuration 277

3.1 Identity Server Advanced Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 277
3.1.1 Managing an Identity Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 278
3.1.2 Editing Server Details . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 280

4 Contents
 3.1.3 Customizing Identity Server. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 281
3.1.4 Configuring the Custom Response Header for an Identity Server Cluster . . . . . . . . . . . . . 318
3.2 Access Gateway Server Advance Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 319
3.2.1 Configuration Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 319
3.2.2 Saving, Applying, or Canceling Configuration Changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . 320
3.2.3 Managing Access Gateways Settings. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 322
3.2.4 Managing General Details of Access Gateway . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 329
3.2.5 Setting Up a Tunnel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 334
3.2.6 Setting the Date and Time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335
3.2.7 Configuring Network Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 336
3.2.8 Enabling Access Gateway to Display Post-Authentication Message. . . . . . . . . . . . . . . . . . 341
3.2.9 Customizing Access Gateway. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 342
3.3 Access Gateway Content Settings. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 348
3.3.1 Configuring Cache Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 348
3.3.2 Controlling Browser Caching . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 350
3.3.3 Configuring a Pin List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 351
3.3.4 Configuring a Purge List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 354
3.3.5 Purging Cached Content. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 354
3.3.6 Apache htcacheclean Tool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 355
3.4 Access Gateway Advanced Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 355
3.4.1 Configuring Global Advanced Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 356
3.4.2 Configuring Advanced Options for a Domain-Based and Path-Based Multi-Homing
Proxy Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 367
3.5 Cookie Mangling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 373
3.6 URL Attribute Filter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 374
3.7 Analytics Server Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 375
3.7.1 Managing Analytics Server. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 375
3.7.2 Managing General Details of Analytics Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 376
3.7.3 Managing Details of a Cluster . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 377
3.7.4 Configuring Analytics Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 377
3.7.5 Importing Analytics Server. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 378
3.8 Email Server Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 379
3.9 Configuration Files Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 380
3.9.1 Modifying web.xml. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 380
3.9.2 Modifying server.xml . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 380

4 Configuring Authentication 383

4.1 Local Authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 383
4.1.1 Configuring Identity User Stores . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 384
4.1.2 Creating Authentication Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 396
4.1.3 Configuring Authentication Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 403
4.1.4 Configuring Authentication Contracts. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 405
4.1.5 Specifying Authentication Defaults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 416
4.1.6 Persistent Authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 417
4.1.7 Mutual SSL (X.509) Authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 420
4.1.8 ORed Credential Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 432
4.1.9 OpenID Authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 433
4.1.10 Password Retrieval . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 434
4.1.11 Configuring Access Manager for NESCM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 436
4.1.12 Kerberos Authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 441
4.2 Federated Authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 455
4.2.1 Configuring Federation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 456
4.2.2 Service Provider Brokering . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 477

Contents 5
 4.2.3 Configuring User Identification Methods for Federation . . . . . . . . . . . . . . . . . . . . . . . . . . 493
4.2.4 Configuring SAML 2.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 501
4.2.5 Configuring SAML 1.1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 544
4.2.6 Configuring Liberty . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 547
4.2.7 Configuring Liberty Web Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 554
4.2.8 Configuring WS Federation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 574
4.2.9 Configuring WS-Trust Security Token Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 603
4.2.10 Understanding How Access Manager Uses OAuth and OpenID Connect . . . . . . . . . . . . . 627
4.2.11 Configuring Authentication Through Federation for Specific Providers. . . . . . . . . . . . . . .666
4.2.12 Integrating Amazon Web Services with Access Manager . . . . . . . . . . . . . . . . . . . . . . . . . . 670
4.2.13 Configuring Single Sign-On for Office 365 Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 674
4.3 Advanced Authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 703
4.3.1 Two-Factor Authentication Using Time-Based One-Time Password . . . . . . . . . . . . . . . . . 703
4.3.2 RADIUS Authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 706
4.3.3 NetIQ Advanced Authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 707
4.4 Social Authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 714
4.4.1 Why and When to Use . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 715
4.4.2 Prerequisites for Social Authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 716
4.4.3 Configuring the Social Authentication Class. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 716
4.4.4 Adding Images for Social Authentication Providers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .718
4.4.5 Changing Social Authentication Icons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 719
4.4.6 Configuring Supported Social Authentication Providers for API Keys and API Secrets . . . 719
4.5 Risk-based Authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 722
4.5.1 How Risk-based Authentication Works. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 724
4.5.2 Why Risk-based Authentication. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 726
4.5.3 Features of Risk-based Authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 727
4.5.4 Key Terms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 733
4.5.5 Understanding Risk-based Authentication through Scenarios . . . . . . . . . . . . . . . . . . . . . . 734
4.5.6 Understanding Risk Score Calculation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 744
4.5.7 Configuring Risk-based Authentication. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 746
4.5.8 Enabling Auditing for Risk-Based Authentication Events. . . . . . . . . . . . . . . . . . . . . . . . . . . 746
4.5.9 Configuring an External Database to Store User History. . . . . . . . . . . . . . . . . . . . . . . . . . . 746
4.5.10 Enabling Logging for Risk-Based Authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 749
4.5.11 Troubleshooting Risk Rule Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .749

5 Device Fingerprinting 755

5.1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . How It
Works . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 755
Device Fingerprinting in Pre-Authentication Scenario . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 756
Device Fingerprinting in Post-authentication Scenario . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 758
5.2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Understanding Device
Fingerprint
Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 760
5.3 Configuring a Device Fingerprint Rule . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 762
5.4 Configuring an Example Device Fingerprint Policy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 763

6 Integrating Access Manager with Microsoft Azure 767

6.1 Automatic Hybrid Azure AD Join for Windows Devices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 767
6.1.1 How Automatic Hybrid Azure AD Join Works. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 768
6.1.2 Setting Up Automatic Hybrid Azure AD Join for Windows Devices . . . . . . . . . . . . . . . . . . 769
6.1.3 Automatic Hybrid Azure AD Join for Windows Downlevel Devices . . . . . . . . . . . . . . . . . . 774
6.1.4 How SSO to Microsoft Azure Applications Work . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 775

6 Contents
 6.1.5 Troubleshooting Automatic Hybrid Azure AD Join. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 775
6.2 Azure AD Join for Windows Devices. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 775
6.2.1 Prerequisites for Azure AD Join . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 775
6.2.2 Configuring Azure AD Join . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 775
6.3 Azure Active Directory Conditional Access with Access Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . 776
6.4 Registering Devices to Microsoft Intune Mobile Device Management. . . . . . . . . . . . . . . . . . . . . . .779

7 Appmarks 781
7.1 Creating an Appmark. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 782
7.2 Creating Multiple Appmarks for an Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 782
7.3 Understanding Appmarks Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 782
7.4 Managing Icons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 784

8 Enabling Mobile Access 785

8.1 Requirements for the MobileAccess App . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 785
8.2 Configuring the MobileAccess App . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 786
8.3 Registering Users Mobile Devices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 787
8.3.1 Registering iOS Devices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 787
8.3.2 Registering Android Devices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 788
8.4 Installing MobileAccess on a Mobile Device . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 789
8.5 Understanding the MobileAccess PIN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 789
8.6 Managing Mobile Devices. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 790
8.6.1 Deregistering Mobile Devices as an Administrator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 791
8.6.2 Deregistering a Mobile Device as a User . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 791
8.6.3 Deleting and Reinstalling the MobileAccess App on a Device . . . . . . . . . . . . . . . . . . . . . . 791

9 Branding of the User Portal Page 793

10 Access Manager Policies 795

10.1 Understanding Policies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 795
10.1.1 Selecting a Policy Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 796
10.1.2 Tuning the Policy Performance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 797
10.1.3 Managing Policies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 797
10.1.4 Managing Policy Containers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 799
10.1.5 Managing a Rule List. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 800
10.1.6 Adding Policy Extensions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 802
10.1.7 Enabling Policy Logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 806
10.2 Role Policies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 807
10.2.1 Understanding RBAC in Access Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 807
10.2.2 Enabling Role-Based Access Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 810
10.2.3 Creating Roles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 811
10.2.4 Example Role Policies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 830
10.2.5 Creating Access Manager Roles in an Existing Role-Based Policy System . . . . . . . . . . . . . 833
10.2.6 Mapping Roles between Trusted Providers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 842
10.2.7 Enabling and Disabling Role Policies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 843
10.2.8 Importing and Exporting Role Policies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 844
10.3 Authorization Policies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 844
10.3.1 Designing an Authorization Policy. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 845
10.3.2 Creating Access Gateway Authorization Policies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 854

Contents 7
 10.3.3 Sample Access Gateway Authorization Policies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 856
10.3.4 Conditions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 862
10.3.5 Importing and Exporting Authorization Policies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 893
10.4 Identity Injection Policies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 893
10.4.1 Designing an Identity Injection Policy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 894
10.4.2 Configuring an Identity Injection Policy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 896
10.4.3 Configuring an Authentication Header Policy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 897
10.4.4 Configuring a Custom Header Policy. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 902
10.4.5 Configuring a Custom Header with Tags. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 904
10.4.6 Specifying a Query String for Injection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 907
10.4.7 Injecting into the Cookie Header. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 909
10.4.8 Configuring an Inject Kerberos Ticket Policy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 910
10.4.9 Configuring an OAuth Token Inject Policy. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .913
10.4.10 Importing and Exporting Identity Injection Policies. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .914
10.4.11 Sample Identity Injection Policy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 914
10.5 Form Fill Policies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 916
10.5.1 Understanding an HTML Form. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 916
10.5.2 Creating a Form Fill Policy for the Sample Form . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 919
10.5.3 Implementing Form Fill Policies. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 921
10.5.4 Creating and Managing Shared Secrets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 938
10.5.5 Importing and Exporting Form Fill Policies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 940
10.5.6 Configuring a Form Fill Policy for Forms With Scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 941
10.6 External Attribute Source Policies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 946
10.6.1 Enabling External Attributes Policy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 946
10.6.2 Creating an External Attribute Source Policy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 946
10.6.3 External Attribute Source Policy Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 947
10.7 Risk-based Policies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 950
10.7.1 Configuring Risk-based Authentication. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 950
10.7.2 Configuring User History . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 961
10.7.3 Configuring Geolocation Profiling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 964
10.7.4 Configuring Behavioral Analytics. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 964
10.7.5 Configuring NAT Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 967
10.7.6 Configuring an Authorization Policy to Protect a Resource. . . . . . . . . . . . . . . . . . . . . . . . . 967
10.7.7 Risk-Based Authentication: Sample Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 968

11 High Availability and Fault Tolerance 973

11.1 Installing Secondary Administration Console . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 973
11.1.1 Prerequisites for Installing Secondary Administration Console . . . . . . . . . . . . . . . . . . . . . 973
11.1.2 Installing Second Console . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 974
11.1.3 Understanding How Consoles Interact with Each Other and with Access Manager
Devices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 975
11.2 Configuration Tips for the L4 Switch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 976
11.2.1 Sticky Bit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 976
11.2.2 Network Configuration Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 976
11.2.3 Health Checks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 978
11.2.4 Real Server Settings Example. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 981
11.2.5 Virtual Server Settings Example. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 981
11.3 Setting up L4 Switch for IPv6 Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 982
11.3.1 Web SSO Over IPv6. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 983
11.3.2 Federated SSO over IPv6 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 984
11.3.3 Limitations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 985
11.4 Using a Software Load Balancer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 985

8 Contents
Part II Security And Certificates 987

12 Securing Access Manager 989

12.1 Securing Administration Console . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 989
12.2 Protecting the Configuration Store . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 990
12.3 Security Considerations for Certificates. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 991
12.4 Configuring Secure Communication on Identity Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 991
12.4.1 Configuring Enhanced Security for Service Provider Communications . . . . . . . . . . . . . . . 992
12.4.2 Viewing the Services That Use the Signing Key PairSigning . . . . . . . . . . . . . . . . . . . . . . . . 992
12.4.3 Viewing Services That Use the Encryption Key PairEncryption. . . . . . . . . . . . . . . . . . . . . . 994
12.4.4 Managing the Keys, Certificates, and Trust Stores. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 994
12.5 Security Considerations for Identity Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 996
12.5.1 Federation Options. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 997
12.5.2 Authentication Contracts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 997
12.5.3 Forcing 128-Bit Encryption. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 998
12.5.4 Configuring the Encryption Method for the SAML Assertion . . . . . . . . . . . . . . . . . . . . . . .999
12.5.5 Configuring SAML 2.0 to Sign Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1000
12.5.6 Blocking Access to Identity Server Pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1001
12.5.7 Using netHSM for the Signing Key Pair . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1001
12.6 Enabling Secure Cookies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1020
12.6.1 Securing the Embedded Service Provider Session Cookie on Access Gateway . . . . . . . .1020
12.6.2 Securing the Proxy Session Cookie . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1021
12.7 Preventing Cross-site Scripting Attacks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1022
12.7.1 Option 1: HTML Escaping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1022
12.7.2 Option 2: Filtering. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1023

13 Setting Up Advanced Session Assurance 1025

Enabling Advanced Session Assurance at the Cluster Level . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1027
Enabling Advanced Session Assurance at the Proxy Service Resource Level . . . . . . . . . . . . . . . . . . . . . . .1027
Best Practices for Enabling Advanced Session Assurance at the Proxy Service Resource Level . .1028
Setting Up Session Validation and Renewal Interval . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1028
Modifying Parameters Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1029
Disabling Advanced Session Assurance. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1029
An Example Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1033

14 Understanding Access Manager Certificates 1035

14.1 Process Flow. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1036
14.2 Access Manager Trust Stores . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1037
14.3 Access Manager Keystores . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1038
14.3.1 Identity Server Keystores . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1039
14.3.2 Access Gateway Keystores . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1039
14.3.3 Keystores When Multiple Devices Are Installed on Administration Console. . . . . . . . . .1040

15 Creating Certificates 1041

15.1 Creating a Locally Signed Certificate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1042
15.2 Editing the Subject Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1043
15.3 Assigning Alternate Subject Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1045
15.4 Generating a Certificate Signing Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1046

Contents 9
 15.5 Importing a Signed Certificate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1047

16 Managing Certificates and Keystores 1049

16.1 Viewing Certificate Details . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1049
16.2 Adding a Certificate to a Keystore . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1051
16.3 Renewing a Certificate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1052
16.4 Exporting a Private/Public Key Pair . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1053
16.5 Exporting a Public Certificate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1054
16.6 Importing a Private/Public Key Pair . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1054
16.7 Managing Certificates in a Keystore. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1055
16.8 Using Multiple External Signing Certificates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1056
Example of Creating an External Keystore and Certificates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1057

17 Assigning Certificates to Access Manager Devices 1059

17.1 Importing a Trusted Root to the LDAP User Store. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1059
17.2 Managing Identity Server Certificates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1060
17.3 Assigning Certificates to an Access Gateway. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1061
17.3.1 Managing Embedded Service Provider Certificates. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1062
17.3.2 Managing Reverse Proxy and Web Server Certificates . . . . . . . . . . . . . . . . . . . . . . . . . . .1062
17.4 Changing a Non-Secure (HTTP) Environment to a Secure (HTTPS) Environment . . . . . . . . . . . . . .1063

18 Managing Trusted Roots and Trust Stores 1065

18.1 Managing Trusted Roots and Trust Stores . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1065
18.1.1 Importing Public Key Certificates (Trusted Roots) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1065
18.1.2 Adding Trusted Roots to Trust Stores . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1066
18.1.3 Auto-Importing Certificates from Servers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1066
18.1.4 Exporting the Public Certificate of a Trusted Root . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1066
18.1.5 Viewing Trust Store Details . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1067
18.1.6 Viewing Trusted Root Details . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1067
18.2 Viewing External Trusted Roots . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1069

19 Enabling SSL Communication 1071

19.1 Enabling SSL Communication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1071
19.1.1 Identifying the SSL Communication Channels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1072
19.1.2 Using Access Manager Certificates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1072
19.1.3 Using Externally Signed Certificates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1074
19.1.4 Using an SSL Terminator. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1079
19.1.5 SSL Renegotiation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1083
19.2 Using SSL on Access Gateway Communication Channels. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1085
19.3 Configuring SSL for Authentication between Identity Server and Access Manager
Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1086
19.4 Prerequisites for SSL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1087
19.4.1 Prerequisites for SSL Communication between Identity Server and Access Gateway . .1087
19.4.2 Prerequisites for SSL Communication between Access Gateway and Web Servers . . . .1087
19.5 Configuring SSL Communication with Browsers and Access Gateway . . . . . . . . . . . . . . . . . . . . . .1088
19.6 Configuring SSL between the Proxy Service and the Web Servers . . . . . . . . . . . . . . . . . . . . . . . . .1090
19.7 Configuring the SSL Communication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1091

10 Contents
Part III Maintaining Access Manager 1093

20 Analytics Dashboard 1095

20.1 Advantages of Using Analytics Dashboard. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1096
20.2 Architecture of Analytics Dashboard . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1096
20.3 Who Can Access Analytics Dashboard . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1097
20.4 Getting Started with Analytics Dashboard. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1097
20.5 Prerequisites for Viewing Graphs on Analytics Dashboard . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1098
20.6 Enabling Events for Each Graph . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1098
20.7 Viewing Data in Analytics Dashboard . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1099
20.7.1 Real-time Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1100
20.7.2 Historic Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1100
20.8 Types of Graphs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1100
20.8.1 Unique Users Logged In . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1101
20.8.2 Active Users . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1101
20.8.3 Access Gateway Active Users. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1101
20.8.4 Geolocation of Users Logged In. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1101
20.8.5 Risky Logins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1101
20.8.6 Most Accessed Access Gateway Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1101
20.8.7 Most Used Browsers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1102
20.8.8 Most Used Endpoint Devices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1102
20.8.9 Most Active Users . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1102
20.8.10 Client IP Addresses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1102
20.8.11 Authentication Methods Used . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1102
20.8.12 Failed Authentications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1102
20.8.13 Logins. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1102
20.8.14 Access Gateway Logins. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1103
20.8.15 Access Gateway Uptime. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1103
20.8.16 Access Gateway Requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1103
20.8.17 Access Gateway Cache Utilization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1103
20.8.18 Identity Server Devices. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1103
20.8.19 Access Gateway Devices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1103
20.9 Accessing Analytics Dashboard. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1103
20.10 Managing Analytics Dashboard . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1103
20.10.1 Managing Layout of a Dashboard . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1104
20.10.2 Exporting and Importing a Customized Dashboard . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1104
20.10.3 Filtering Data to View Required Details . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1105
20.10.4 Adding or Modifying Refresh Time for the Real-time Dashboard . . . . . . . . . . . . . . . . . .1105
20.10.5 Creating Visualization. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1105
20.10.6 Creating a Custom Dashboard . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1106
20.10.7 Customizing the Views of Graphs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1106
20.10.8 Discovering Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1108
20.10.9 Logging Analytics Server Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1109

21 Auditing 1111
21.1 Setting Up Logging Server and Console Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1112
21.2 Important Points to Consider When Using Syslog. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1116
21.2.1 Limitations of Syslog. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1116
21.2.2 Caching Audit Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1117
21.2.3 Debugging Syslog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1117
21.3 Configuring Syslog for Auditing over UDP and TLS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1117

Contents 11
 21.3.1 Auditing using UDP. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1117
21.3.2 Auditing using TLS over TCP. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1118
21.3.3 Configuring Administration Console as a Remote Audit Server . . . . . . . . . . . . . . . . . . . .1120
21.4 Enabling Identity Server Audit Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1121
21.5 Enabling Access Gateway Audit Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1125

22 Reporting 1127
22.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1127
22.2 Using Reporting with Sentinel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1128
22.2.1 Prerequisites for Using Access Manager Reporting Solution Pack . . . . . . . . . . . . . . . . . .1128
22.2.2 Deploying Access Manager Reporting Solution Pack. . . . . . . . . . . . . . . . . . . . . . . . . . . . .1129
22.3 Using Reporting with Analytics Server. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1129
22.3.1 Prerequisites for Using Reporting with Analytics Server . . . . . . . . . . . . . . . . . . . . . . . . . .1129
22.3.2 Viewing Reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1130
22.4 Enabling Reporting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1130
22.5 Generating Reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1131

23 Logging 1133
23.1 Understanding the Types of Logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1133
23.1.1 Component Logging for Troubleshooting Configuration or Network Problems . . . . . . .1134
23.1.2 HTTP Transaction Logging for Proxy Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1134
23.2 Understanding the Log Format. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1135
23.2.1 Understanding the Correlation Tags in the Log Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1136
23.2.2 Sample Scenario . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1138
23.3 Identity Server Logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1138
23.3.1 Configuring Logging for Identity Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1138
23.3.2 Configuring Session-Based Logging. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1140
23.3.3 Capturing Stack Traces of Exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1147
23.4 Access Gateway Logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1148
23.4.1 Managing Access Gateway Logs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1149
23.4.2 Configuring Logging of HTTP Headers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1150
23.4.3 Configuring Logging of SOAP Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1151
23.4.4 Configuring Logging for a Proxy Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1151
23.5 Downloading Log Files. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1160
23.5.1 Linux Administration Console Logs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1161
23.5.2 Windows Server 2016 Administration Console Logs . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1161
23.5.3 Linux Identity Server Logs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1162
23.5.4 Windows Server 2012 Identity Server Logs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1162
23.5.5 Linux Access Gateway Appliance and Access Gateway Service Logs . . . . . . . . . . . . . . . .1163
23.5.6 Windows Access Gateway Service Logs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1163
23.6 Turning on Logging for Policy Evaluation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1164

24 Monitoring Component Statistics 1167

24.1 Identity Server Statistics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1167
24.1.1 Monitoring Identity Server Statistics. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1167
24.1.2 Monitoring Identity Server Cluster Statistics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1177
24.2 Access Gateway Statistics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1177
24.2.1 Monitoring Access Gateway Statistics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1177
24.2.2 Monitoring Access Gateway Cluster Statistics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1187
24.3 Component Statistics Through REST APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1189

12 Contents
 24.3.1 Monitoring API for Identity Server Statistics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1189
24.3.2 Monitoring API for Access Gateway Statistics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1195

25 Monitoring Component Command Status 1199

25.1 Viewing the Command Status of Identity Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1199
25.1.1 Viewing the Status of Current Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1199
25.1.2 Viewing Detailed Command Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1200
25.2 Viewing the Command Status of Access Gateway . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1200
25.2.1 Viewing the Status of Current Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1200
25.2.2 Viewing Detailed Command Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1201
25.3 Viewing the Command Status of Analytics Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1202
25.3.1 Viewing the Status of Current Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1202
25.3.2 Viewing Detailed Command Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1202
25.4 Reviewing the Command Status for Certificates. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1203

26 Monitoring Server Health 1205

26.1 Health States . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1205
26.2 Monitoring Health by Using the Hardware IP Address . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1206
26.3 Monitoring Health of Identity Servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1206
26.3.1 Monitoring Health of an Identity Server. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1206
26.3.2 Monitoring Health of an Identity Server Cluster . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1208
26.4 Monitoring Health of Access Gateways . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1208
26.4.1 Monitoring Health of an Access Gateway. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1208
26.4.2 Monitoring Health of an Access Gateway Cluster . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1213
26.5 Monitoring Health of Analytics Server. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1213
26.5.1 Monitoring Health of Analytics Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1213
26.5.2 Monitoring the Health of Analytics Server Cluster . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1214
26.6 Monitoring Health of Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1215

27 Monitoring Alerts 1217

27.1 Monitoring Identity Server Alerts. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1217
27.2 Monitoring Access Gateway Alerts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1217
27.2.1 Viewing Access Gateway Alerts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1217
27.2.2 Viewing Access Gateway Cluster Alerts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1218
27.2.3 Managing Access Gateway Alert Profiles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1218
27.2.4 Configuring an Alert Profile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1218
27.2.5 SNMP Profile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1220
27.2.6 Configuring a Log Profile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1220
27.2.7 Configuring an E-Mail Profile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1221
27.2.8 Configuring a Syslog Profile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1221
27.3 Monitoring Analytics Server Alerts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1221
27.3.1 Viewing Analytics Server Alerts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1222
27.3.2 Viewing Analytics Server Cluster Alerts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1222

28 Monitoring Access Manager By Using Simple Network Management Protocol 1223

28.1 SNMP Architecture in Access Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1223
28.2 Features of Monitoring in Access Manager. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1224
28.3 Using the Default MIB File with External SNMP Systems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1225
28.4 Querying For SNMP Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1226

Contents 13
 28.4.1 Querying Using the Namespace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1227
28.4.2 Querying Using the OID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1227
28.5 Installing and Enabling Monitoring for Access Manager Components . . . . . . . . . . . . . . . . . . . . . .1228
28.5.1 Installing and Enabling Monitoring for Access Manager on Linux . . . . . . . . . . . . . . . . . .1228
28.5.2 Installing and Enabling Monitoring for Access Manager on Windows . . . . . . . . . . . . . . .1228

29 Impersonation 1231
29.1 Prerequisites for Creating an Impersonated Session . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1231
29.2 Enabling Impersonation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1232
29.3 Impersonation Flow. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1232
29.4 Implementing Impersonation in Custom Portal Pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1232
29.4.1 Understanding the Specific JSP Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1233
29.4.2 Determining when to Show the Specific JSP Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1233
29.5 Audit Event for Impersonation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1235
29.6 Troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1235

30 Back Up and Restore 1237

30.1 How The Backup and Restore Process Works . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1237
30.1.1 Default Parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1237
30.1.2 The Process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1238
30.2 Backing Up the Access Manager Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1238
30.3 Restoring the Access Manager Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1240
30.3.1 Restoring the Configuration on a Standalone Administration Console . . . . . . . . . . . . . .1240
30.3.2 Restoring the Configuration with an Identity Server on the Same Machine . . . . . . . . . .1241
30.4 Restoring an Identity Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1243
30.5 Restoring an Access Gateway . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1243
30.5.1 Clustered Access Gateway . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1244
30.5.2 Single Access Gateway . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1244

31 Code Promotion 1245

31.1 How Code Promotion Helps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1245
31.2 Sequence of Promoting the Configuration Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1246
31.3 Prerequisites for Performing Code Promotion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1246
31.4 Configuring Custom File Paths . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1247
31.5 Exporting the Configuration Data. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1248
31.6 Importing the Configuration Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1250
31.6.1 Uploading Configuration File to Import . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1250
31.6.2 Selecting the Component to Import the Configuration Data . . . . . . . . . . . . . . . . . . . . . .1251
31.6.3 Importing Identity Server Configuration Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1251
31.6.4 Importing Access Gateway Configuration Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1252
31.6.5 Post-Import Configuration Tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1256
31.7 Troubleshooting Code Promotion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1257
31.8 Code Promotion Limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1258

32 Troubleshooting 1259
32.1 Troubleshooting Administration Console . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1259
32.1.1 Global Troubleshooting Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1260
32.1.2 Diagnostic Configuration Export Utility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1264

14 Contents
 32.1.3
Stopping Tomcat on Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1264
32.1.4
Restoring a Failed Secondary Console . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1265
32.1.5
Moving the Primary Administration Console to a New Hardware . . . . . . . . . . . . . . . . . .1265
32.1.6
Converting a Secondary Administration Console into a Primary Console . . . . . . . . . . . .1266
32.1.7
Repairing the Configuration Datastore . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1273
32.1.8
Session Conflicts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1274
32.1.9
Unable to Log In to Administration Console. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1274
32.1.10
(Linux) Exception Processing IdentityService_ServerPage.JSP . . . . . . . . . . . . . . . . . . . . .1275
32.1.11
Backup and Restore Fail Because of Special Characters in Passwords . . . . . . . . . . . . . . .1275
32.1.12
Unable to Install NMAS SAML Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1276
32.1.13
Incorrect Audit Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1276
32.1.14
Unable to Update Access Gateway Listening IP Address in Administration Console
Reverse Proxy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1277
32.1.15 During Access Gateway Installation Any Error Message Should Not Display
Successful Status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1278
32.1.16 Incorrect Health Is Reported on Access Gateway . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1278
32.1.17 Administration Console Does Not Refresh the Command Status Automatically . . . . . .1278
32.1.18 SSL Communication with Weak Ciphers Fails . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1278
32.1.19 Error: Tomcat did not stop in time. PID file was not removed . . . . . . . . . . . . . . . . . . . . .1279
32.1.20 (Access Manager on Cloud) Metadata Under System Setup of SAML 2 Applications
Is Displayed after a delay of 5 to 10 Seconds . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1279
32.1.21 (Windows) Advanced Authentication Configuration Details Are Not Applied to a
New Node of the Identity Server Cluster . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1279
32.2 Troubleshooting Access Gateway . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1279
32.2.1 Useful Troubleshooting Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1280
32.2.2 Verifying That All Services Are Running . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1284
32.2.3 Microsoft Office Documents Do Not Open When SharePoint Is Accelerated by
Access Gateway Appliance. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1286
32.2.4 Troubleshooting SSL Connection Issues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1287
32.2.5 Enabling Debug Mode and Core Dumps. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1287
32.2.6 Useful Troubleshooting Tools for Access Gateway Service . . . . . . . . . . . . . . . . . . . . . . . .1290
32.2.7 Solving Apache Restart Issues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1291
32.2.8 Understanding the Authentication Process of Access Gateway Service . . . . . . . . . . . . .1294
32.2.9 Issue While Accelerating the Ajax Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1300
32.2.10 Accessing Lotus-iNotes through Access Gateway Asks for Authentication . . . . . . . . . . .1300
32.2.11 Configuration Issues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1300
32.2.12 The Embedded Service Provider Does not Start . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1301
32.2.13 Cannot Inject a Photo into HTTP Headers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1301
32.2.14 Reimporting Access Gateway Takes the IP Address of the Old Administration
Console . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1301
32.2.15 Reimporting Access Gateway Service Fails on Windows 2012 R2 Server . . . . . . . . . . . .1301
32.2.16 Access Gateway Caching Issues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1302
32.2.17 Issues while Changing the Management IP Address in Access Gateway Appliance . . . .1302
32.2.18 Issue While Adding Access Gateway in a Cluster . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1303
32.2.19 Access Gateway Fails to Start After Upgrading SLES 11 SP3 to SLES 12 . . . . . . . . . . . . . .1304
32.3 Troubleshooting Identity Server and Authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1304
32.3.1 Useful Networking Tools for Linux Identity Server. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1306
32.3.2 Troubleshooting 100101043 and 100101044 Liberty Metadata Load Errors . . . . . . . . .1306
32.3.3 Authentication Issues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1314
32.3.4 Problems Reading Keystores after Identity Server Re-installation . . . . . . . . . . . . . . . . . .1318
32.3.5 After Setting Up the User Store to Use SecretStore, Users Report 500 Errors . . . . . . . .1318
32.3.6 When Multiple Browser Logout Option Is Enabled, User Is Not Getting Logged Out
from Different Sessions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1318
32.3.7 After Consuming a SAML Response, the Browser Is Redirected to an Incorrect URL . . .1318

Contents 15
 32.3.8
Configuring SAML 1.1 Identity Provider Without Specifying Port in the Login URL
Field . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1318
32.3.9 Attributes Are Not Available Through Form Fill When OIOSAML Is Enabled. . . . . . . . . .1319
32.3.10 Issue in Importing Metadata While Configuring Identity Provider or Service
Provider Using Metadata URL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1319
32.3.11 Enabling Secure or HTTPOnly Flags for Cluster Cookies . . . . . . . . . . . . . . . . . . . . . . . . . .1319
32.3.12 Apache Portable Runtime Native Library Does Not Get Loaded in Tomcat . . . . . . . . . . .1320
32.3.13 Metadata Mentions Triple Des As Encryption Method . . . . . . . . . . . . . . . . . . . . . . . . . .1322
32.3.14 Issue in Accessing Protected Resources with External Identity Provider When Both
Providers Use Same Cookie Domain . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1322
32.3.15 SAML Intersite Transfer URL Setup Does Not Work for Non-brokered Setups after
Enabling SP Brokering . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1322
32.3.16 Orphaned Identity Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1322
32.3.17 Users Cannot Log In to Identity Server When They Access Protected Resources
with Any Contract Assigned . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1323
32.3.18 An Attribute Query from OIOSAML.SP Java Service Provider Fails with Null Pointer . . .1323
32.3.19 Disabling the Certificate Revocation List Checking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1324
32.3.20 Step Up Authentication for Identity Server Initiated SSO to External Provider Does
Not Work Unless It has a Matching Local Contract . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1324
32.3.21 Metadata Cannot be Retrieved from the URL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1324
32.3.22 Authentication Request to a Service Provider Fails . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1324
32.3.23 SAML 2.0 POST Compression Failure Does Not Throw a Specific Error Code . . . . . . . . .1324
32.3.24 SAML 1.1 Service Provider Re-requests for Authentication . . . . . . . . . . . . . . . . . . . . . . .1325
32.3.25 Issue in Generating WS-Federation Claim for SharePoint 2010 On Windows . . . . . . . . .1325
32.3.26 Identity Server Statistics Logs Do Not Get Written In Less Than One Minute . . . . . . . . .1325
32.3.27 No Error Message Is Written in the Log File When an Expired Certificate Is Used for
the X509 Authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1326
32.3.28 Terminating an Existing Authenticated User from Identity Server . . . . . . . . . . . . . . . . . .1326
32.3.29 Clustered Nodes Looping Due to JGroup Issues. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1327
32.3.30 Authentication With Aliases Fails . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1327
32.3.31 nidp/app Does Not Redirect to nidp/portal after Authentication . . . . . . . . . . . . . . . . . .1328
32.3.32 Login to Office 365 Fails when WS-Trust MEX Metadata Is Larger than 65 KB . . . . . . . .1328
32.3.33 Unsafe Server Certificate Change in SSL/TLS Renegotiations Is Not Allowed . . . . . . . . .1328
32.3.34 Viewing Request and Response Headers of All Protocols in a Log File . . . . . . . . . . . . . .1329
32.3.35 Provisioning of LDAP Attribute for Social Authentication User Failed . . . . . . . . . . . . . . .1330
32.3.36 User Authentication Fails When the Advanced Authentication Generic Class Is
Used. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1330
32.3.37 Cannot Create an Authentication Class with Advanced Authentication Generic
Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1330
32.3.38 CORS Request to the Token Introspection Endpoint Fails . . . . . . . . . . . . . . . . . . . . . . . . .1331
32.3.39 The User Portal Page Does Not Display the Branding . . . . . . . . . . . . . . . . . . . . . . . . . . . .1332
32.4 Troubleshooting Analytics Server. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1332
32.4.1 Launching Access Manager Dashboard Displays a Blank Page . . . . . . . . . . . . . . . . . . . . .1333
32.4.2 Graphs Do Not Display Any Data When You Launch Access Manager Dashboard . . . . .1333
32.4.3 Clearing the Existing Realtime Data to View the Imminent Data on Graphs . . . . . . . . . .1333
32.4.4 Cannot Launch Access Manager Dashboard After Reimporting Analytics server . . . . . .1334
32.4.5 The Analytics Server Health Is Not Reported to Administration Console . . . . . . . . . . . .1334
32.4.6 Access Manager Dashboard Does Not Display Graphs, but Displays the Health
Status of Devices. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1334
32.5 Troubleshooting Certificate Issues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1336
32.5.1 Resolving the JCC Communication between Devices and Administration Console . . . .1336
32.5.2 The Self-Signing Certificate Is Expired for Port 10013 on Analytics Server . . . . . . . . . . .1337
32.5.3 Resolving Certificate Import Issues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1337
32.5.4 Mutual SSL with X.509 Produces Untrusted Chain Messages. . . . . . . . . . . . . . . . . . . . . .1339
32.5.5 Certificate Command Failure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1340

16 Contents
 32.5.6 Cannot Log In with Certificate Error Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1340
32.5.7 When a User Accesses a Resource, the Browser Displays Certificate Errors . . . . . . . . . .1340
32.5.8 Canceling Certificates Modification Results in Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . .1341
32.5.9 A Device Reports Certificate Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1341
32.5.10 Renewing the expired eDirectory certificates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1341
32.5.11 Certificate Trust Store Objects of the Identity Server Clusters Are Deleted
Randomly . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1341
32.6 Troubleshooting Access Manager Policies. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1342
32.6.1 Turning on Logging for Policy Evaluation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1342
32.6.2 Common Configuration Problems That Prevent a Policy from Being Applied as
Expected . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1344
32.6.3 The Policy Is Using Old User Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1346
32.6.4 Form Fill and Identity Injection Silently Fail . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1348
32.6.5 Checking for Corrupted Policies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1348
32.6.6 Policy Page Timeout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1348
32.6.7 Policy Creation and Storage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1348
32.6.8 Policy Distribution. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1349
32.6.9 Policy Evaluation: Access Gateway Devices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1350
32.7 Troubleshooting MobileAccess. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1354
32.7.1 Using the Same Mobile Device for Different Users Causes the Expired Session Error . .1355
32.7.2 Simple Authentication with a Pop-up Browser Window Does Not Work for
MobileAccess . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1355
32.7.3 Users Fail to Authenticate to MobileAccess when Appmarks Are Launched in the
Chrome Browser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1355
32.7.4 Changes to MobileAccess do not Appear in Administration Console . . . . . . . . . . . . . . .1355
32.7.5 Facebook Basic SSO Connector Does Not Work from MobileAccess . . . . . . . . . . . . . . . .1356
32.8 Troubleshooting Code Promotion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1357
32.8.1 Troubleshooting Identity Server Code Promotion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1357
32.8.2 Troubleshooting Access Gateway Code Promotion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1358
32.8.3 Troubleshooting Device Customization Code Promotion . . . . . . . . . . . . . . . . . . . . . . . . .1362
32.9 Troubleshooting the Device Fingerprint Rule . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1362
32.9.1 Enabling the Debug Option for the Device Fingerprint Rule. . . . . . . . . . . . . . . . . . . . . . .1362
32.9.2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using
Logs to
Understand
How the
Device
Fingerprint Rule Is
Evaluated . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1363
32.10 Troubleshooting Advanced Session Assurance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1368
32.10.1 Troubleshooting Using the Log Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1368
32.10.2 Important Error Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1373
32.10.3 Checking Session Assurance Configuration Details . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1374
32.10.4 The Advanced Session Assurance Page Does Not Display the Access Gateway
Cluster . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1376
32.11 Troubleshooting XML Validation Errors on Access Gateway Appliance . . . . . . . . . . . . . . . . . . . . .1376
32.11.1 Modifying a Configuration That References a Removed Object . . . . . . . . . . . . . . . . . . . .1377
32.11.2 Configuration UI Writes Incorrect Information to the Local Configuration Store . . . . . .1379
32.12 Troubleshooting OAuth and OpenID Connect. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1383
32.12.1 The Token Endpoint Returns the Invalid Code Error Message . . . . . . . . . . . . . . . . . . . . .1383
32.12.2 OAuth Tokens Are in Binary Format Instead of JWT Format . . . . . . . . . . . . . . . . . . . . . . .1384
32.12.3 Users Cannot Register a Client Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1384
32.12.4 Token Exchanges Show Redirect URI Invalid Error . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1384
32.12.5 Users Cannot Register or Modify a Client Application with Specific Options . . . . . . . . .1384

Contents 17
 32.12.6 A Specific Claim Does Not Come to the UserInfo Endpoint during Claims Request . . . .1384
32.12.7 Access Gateway OAuth Fails . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1385
32.12.8 After Allowing Consent, 500 Internal Server Error Occurs . . . . . . . . . . . . . . . . . . . . . . . .1385
32.12.9 The Access Token Does Not Get Exchanged with Authorization Code When Using a
Multi-Node Identity Server Cluster . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1385
32.12.10No Error Message When a Token Request Contains Repetitive Parameters . . . . . . . . . .1385
32.12.11OAuth Token Encryption/Signing Key Is Compromised or Corrupted . . . . . . . . . . . . . . .1385
32.12.12Tracing OAuth Requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1386
32.12.13OAuth Client Registration Fails If a Role Policy Contains a Condition Other than
LDAP Attribute, LDAP Group, or LDAP OU . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1386
32.12.14The Identity Injection Policy Does Not Inject Passwords. . . . . . . . . . . . . . . . . . . . . . . . . .1387
32.12.15OAuth Apps Fail After Upgrading Access Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1387
32.12.16Authorization Server Responds with the Service Unavailable Message for a
Revocation Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1387
32.12.17(Windows) Cannot Configure Some of the OAuth Features After an Upgrade . . . . . . . .1387
32.13 Troubleshooting User Attribute Retrieval and Transformation . . . . . . . . . . . . . . . . . . . . . . . . . . . .1389
32.13.1 No Value Is Fetched from Attribute Source in Identity Server . . . . . . . . . . . . . . . . . . . . .1390
32.13.2 Error Message While Testing a Database Connection . . . . . . . . . . . . . . . . . . . . . . . . . . . .1390
32.13.3 Regex Replace Error Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1391
32.14 Troubleshooting Impersonation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1391
32.14.1 Internet Explorer Caching Error. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1391
32.15 Troubleshooting Branding. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1391
32.15.1 Changes to Branding do not Appear in Administration Console . . . . . . . . . . . . . . . . . . .1391
32.16 Using Log Files for Troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1392
32.16.1 Sample Authentication Traces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1393
32.16.2 Understanding Policy Evaluation Traces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1397
32.16.3 Adding Hashed Cookies into Browsers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1416
32.17 Access Manager Audit Events and Data. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1418
32.18 Event Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1418

33 Access Manager Audit Events and Data 1419

33.1 JavaScript Object Notation (JSON) Event Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1423
33.2 NIDS: Sent a Federate Request (002e0001). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1424
33.3 NIDS: Received a Federate Request (002e0002) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1425
33.4 NIDS: Sent a Defederate Request (002e0003). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1425
33.5 NIDS: Received a Defederate Request (002e0004) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1426
33.6 NIDS: Sent a Register Name Request (002e0005). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1426
33.7 NIDS: Received a Register Name Request (002e0006) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1426
33.8 NIDS: Logged Out an Authentication that Was Provided to a Remote Consumer (002e0007). . .1427
33.9 NIDS: Logged out a Local Authentication (002e0008) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1427
33.10 NIDS: Provided an Authentication to a Remote Consumer (002e0009) . . . . . . . . . . . . . . . . . . . . .1428
33.11 NIDS: User Session Was Authenticated (002e000a) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1429
33.12 NIDS: Failed to Provide an Authentication to a Remote Consumer (002e000b) . . . . . . . . . . . . . .1429
33.13 NIDS: User Session Authentication Failed (002e000c) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1430
33.14 NIDS: Received an Attribute Query Request (002e000d) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1430
33.15 NIDS: User Account Provisioned (002e000e) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1431
33.16 NIDS: Failed to Provision a User Account (002e000f) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1431
33.17 NIDS: Web Service Query (002e0010) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1432
33.18 NIDS: Web Service Modify (002e0011) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1432
33.19 NIDS: Connection to User Store Replica Lost (002e0012) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1433
33.20 NIDS: Connection to User Store Replica Reestablished (002e0013) . . . . . . . . . . . . . . . . . . . . . . . .1434

18 Contents
33.21 NIDS: Server Started (002e0014) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1434
33.22 NIDS: Server Stopped (002e0015) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1435
33.23 NIDS: Server Refreshed (002e0016). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1435
33.24 NIDS: Intruder Lockout (002e0017) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1436
33.25 NIDS: Severe Component Log Entry (002e0018). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1436
33.26 NIDS: Warning Component Log Entry (002e0019) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1437
33.27 NIDS: Failed to Broker an Authentication from Identity Provider to Service Provider as
Identity Provider and Service Provider Are not in Same Group (002E001A) . . . . . . . . . . . . . . . . .1437
33.28 NIDS: Failed to Broker an Authentication from Identity Provider to Service Provider Because
a Policy Evaluated to Deny (002E001B) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1438
33.29 NIDS: Brokered an Authentication from Identity Provider to Service Provider (002E001C) . . . . .1438
33.30 NIDS: Web service Request was authenticated (002e001D) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1439
33.31 NIDS: Web service Request for authentication Failed (002e001E) . . . . . . . . . . . . . . . . . . . . . . . . .1439
33.32 NIDS: OAuth2 Authorization code issued (002e0028) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1440
33.33 NIDS: OAuth2 token issued (002e0029). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1440
33.34 NIDS: OAuth2 Authorization code issue failed (002e0030) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1441
33.35 NIDS: OpenID token issued (002e0031). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1441
33.36 NIDS: OAuth2 refresh token issued (002e0032) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1442
33.37 NIDS: OAuth2 token issue failed (002e0033) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1442
33.38 NIDS: OpenID token issue failed (002e0034). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1443
33.39 NIDS: OAuth2 refresh token issue failed (002e0035) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1443
33.40 NIDS: OAuth2 client has been registered successfully (002e0036) . . . . . . . . . . . . . . . . . . . . . . . . .1444
33.41 NIDS: OAuth2 client has been modified successfully (002e0037) . . . . . . . . . . . . . . . . . . . . . . . . . .1444
33.42 NIDS: OAuth2 client has been deleted successfully (002e0038) . . . . . . . . . . . . . . . . . . . . . . . . . . .1445
33.43 NIDS: OAuth2 user has provided consent (002e0039) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1445
33.44 NIDS: OAuth2 user has revoked consent (002e0040). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1446
33.45 NIDS: OAuth2 token validation success (002e0041). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1446
33.46 NIDS: OAuth2 token validation failed (002e0042) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1447
33.47 NIDS: OAuth2 client registration failed (002e0043) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1447
33.48 NIDS: OAuth2 refresh token revoked success (002e0055) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1448
33.49 NIDS: OAuth2 refresh token revocation failed (002e0056) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1448
33.50 NIDS: OAuth2 Authorization none issued (002e0057) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1449
33.51 NIDS: OAuth2 AA Authorization Code Exchange (002e0071) . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1449
33.52 NIDS: OAuth2 AA Access Token Exchange (002e0072) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1450
33.53 NIDS: Step-up authentication (002e0719). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1451
33.54 NIDS: Roles PEP Configured (002e0300) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1451
33.55 NIDS: Risk-Based Authentication Action for User (002e0045) . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1451
33.56 NIDS: Risk-Based Authentication Action for User (002e0046) . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1452
33.57 NIDS: Risk-Based Authentication Action for User (002e0047) . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1453
33.58 NIDS: Token was Issued to Web Service (002E001F) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1453
33.59 NIDS: Issued a Federation Assertion (002E0102) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1454
33.60 NIDS: Received a Federation Assertion (002E0103) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1454
33.61 NIDS: Assertion Information (002E0104). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1454
33.62 NIDS: Sent a Federation Request (002E0105) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1455
33.63 Access Gateway: PEP Configured (002e0301) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1455
33.64 Roles Assignment Policy Evaluation (002e0320). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1456
33.65 Access Gateway: Authorization Policy Evaluation (002e0321) . . . . . . . . . . . . . . . . . . . . . . . . . . . .1456
33.66 Access Gateway: Form Fill Policy Evaluation (002e0322) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1457
33.67 Access Gateway: Identity Injection Policy Evaluation (002e0323). . . . . . . . . . . . . . . . . . . . . . . . . .1457

Contents 19
 33.68 Access Gateway: Access Denied (0x002e0505). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1458
33.69 Access Gateway: URL Not Found (0x002e0508) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1458
33.70 Access Gateway: System Started (0x002e0509) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1459
33.71 Access Gateway: System Shutdown (0x002e050a) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1459
33.72 Access Gateway: Identity Injection Parameters (0x002e050c) . . . . . . . . . . . . . . . . . . . . . . . . . . . .1460
33.73 Access Gateway: Identity Injection Failed (0x002e050d) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1461
33.74 Access Gateway: Form Fill Authentication (0x002e050e) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1461
33.75 Access Gateway: Form Fill Authentication Failed (0x002e050f) . . . . . . . . . . . . . . . . . . . . . . . . . . .1462
33.76 Access Gateway: URL Accessed (0x002e0512) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1463
33.77 Access Gateway: IP Access Attempted (0x002e0513) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1463
33.78 Access Gateway: Webserver Down (0x002e0515) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1464
33.79 Access Gateway: All WebServers for a Service is Down (0x002e0516) . . . . . . . . . . . . . . . . . . . . . .1464
33.80 Access Gateway: Application Accessed (002E0514) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1465
33.81 Access Gateway: Session Created (002E0525) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1466
33.82 Management Communication Channel: Health Change (0x002e0601) . . . . . . . . . . . . . . . . . . . . .1466
33.83 Management Communication Channel: Device Imported (0x002e0602) . . . . . . . . . . . . . . . . . . .1467
33.84 Management Communication Channel: Device Deleted (0x002e0603) . . . . . . . . . . . . . . . . . . . . .1467
33.85 Management Communication Channel: Device Configuration Changed (0x002e0604) . . . . . . . .1468
33.86 Management Communication Channel: Device Alert (0x002e0605) . . . . . . . . . . . . . . . . . . . . . . .1469
33.87 Management Communication Channel: Statistics (002e0606) . . . . . . . . . . . . . . . . . . . . . . . . . . . .1469
33.88 Risk-Based Authentication Successful (002e0025) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1470
33.89 Risk-Based Authentication Failed (002e0026). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1470
33.90 Risk-Based Authentication for User (002e0027) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1471
33.91 Impersonation Sign in (002E0048) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1471
33.92 Impersonation: Impersonator Logs Out (002E0049) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1472
33.93 Impersonation: Session Started (002E0050) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1473
33.94 Impersonation: Impersonatee Denies (002E0051) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1473
33.95 Impersonation: Impersonatee Approves (002E0052). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1474
33.96 Impersonation: Impersonator Cancels (002E0053) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1474
33.97 Impersonation: Authorization Policy Fails (002E0054) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1475

34 Event Codes 1477

34.1 Administration Console (009) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1477
34.2 Identity Server (001) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1511
34.3 Linux Access Gateway Appliance(045) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1555
34.4 Access Gateway Service (046) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1556
34.5 Server Communications (JCC) (007) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1560
34.6 Policy Engine (008) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1577
34.7 SOAP Policy Enforcement Point (011) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1581
34.8 Backup and Restore (010) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1585
34.9 Modular Authentication Class (012) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1591

Part IV Appendix 1593

A Data Model Extension XML 1595

Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1595
Writing Data Model Extension XML. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1598

20 Contents
B SOAP versus REST API 1601

C OAuth versus Other Protocols 1603

D OAuth Concepts 1605

D.1 OAuth Terminology . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1605
D.2 Why OpenID Connect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1606
D.3 OAuth Authorization Grant . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1606
D.3.1 Authorization Code Grant (Web Server). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1607
D.3.2 Implicit Grant . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1607
D.3.3 Resource Owner Credential Grant . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1608
D.3.4 Client Credential Grant . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1609
D.3.5 Security Assertion Markup Language (SAML) 2.0 Bearer Grant . . . . . . . . . . . . . . . . . . . .1609
D.4 Authentication Flows. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1609
D.4.1 Authentication by Using the Authorization Code Flow . . . . . . . . . . . . . . . . . . . . . . . . . . .1609
D.4.2 Authentication by Using the Implicit Flow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1610
D.4.3 Authentication by Using Hybrid Flow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1610
D.5 End User Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1611
D.5.1 User Authorization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1611
D.5.2 Revoking Authorizations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1611

E Access Manager Reports Samples 1613

Application Access Summary Report. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1614
User Application Access Summary Report . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1615
Application Specific User Access Report . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1616
Federation Summary Report . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1617
User Login Contract Summary Report. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1618
User Login Failure Report . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1619
Application Specific Risk based Authentication Report . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1620

Contents 21
22
About this Book and the Library

The Administration Guide provides an introduction to NetIQ Access Manager and details about how
to configure and maintain Access Manager features.
To know more about Access Manager, see Access Manager Overview.

Intended Audience
This book 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/TLS)
 Hypertext Transfer Protocol (HTTP and HTTPS)
 Uniform Resource Identifiers (URIs)
 Domain Name System (DNS)
 Web Services Description Language (WSDL)

Other Information in the Library

You can access other information resources in the library at the following locations:
Access Manager Product Documentation (https://www.netiq.com/documentation/access-manager/
index.html)
Access Manager Developer Resources (https://www.netiq.com/documentation/access-manager-45-
developer-documentation/)

NOTE: Contact [email protected] for any query related to Access Manager SDK.

About this Book and the Library 23

24 About this Book and the Library
I Configuring Access Manager
I

This section describes how to setup a basic Access Manager configuration, perform common
administration tasks, and manage components’ configuration. For configuring Access Manager, you
can use the latest version of Internet Explorer, Chrome, or Firefox browsers.
Topics include:
 Chapter 1, “Configuring Administration Console,” on page 27
 Chapter 2, “Setting Up a Basic Access Manager Configuration,” on page 43
 Chapter 3, “Setting Up an Advanced Access Manager Configuration,” on page 277
 Chapter 4, “Configuring Authentication,” on page 383
 Chapter 5, “Device Fingerprinting,” on page 755
 Chapter 6, “Integrating Access Manager with Microsoft Azure,” on page 767
 Chapter 7, “Appmarks,” on page 781
 Chapter 8, “Enabling Mobile Access,” on page 785
 Chapter 9, “Branding of the User Portal Page,” on page 793
 Chapter 10, “Access Manager Policies,” on page 795
 Chapter 11, “High Availability and Fault Tolerance,” on page 973

Configuring Access Manager 25

26 Configuring Access Manager
1 Configuring Administration Console
1

 Section 1.1, “Configuring the Default View,” on page 27

 Section 1.2, “Managing Administration Console Session Timeout,” on page 29
 Section 1.3, “Managing Administrators,” on page 30
 Section 1.4, “Changing the IP Address of Access Manager Devices,” on page 37
 Section 1.5, “Mapping the Private IP Address to Public IP Address,” on page 41

1.1 Configuring the Default View

Access Manager has two views in Administration Console. Access Manager and its Support Packs
used the Roles and Tasks view, with Access Manager the first listed task in the left hand navigation
frame. It looks similar to the following:

This view allows you to quickly access other tasks that you occasionally need to manage the
configuration of the datastore are visible.

Configuring Administration Console 27

 Access Manager looks similar to the following:

This view has the following advantages:

 You can expand and collapse the containers to see as much or as little as you want. For example,
you can see the containers for the policies or you can see the containers and all of the policies in
the container.
 You see the Access Manager components in one view. If you expand the view, any item
displayed you can click on it and Administration Console takes you to the configuration page for
that component.
 Your common tasks are easily accessed through the dashboard. For example, you quickly
access:
 Auditing
 Certificates
 Troubleshooting
 You can see the health of the different Access Manager components from the dashboard. If the
component is healthy, the icons are green. If the components are not healthy, the icons are
yellow and red.
 You can navigate faster than in the Roles and Tasks view.

When you install or upgrade Access Manager and log in to Administration Console, the default view
is set to the Access Manager view.

28 Configuring Administration Console

1.1.1 Changing the View
1 In Administration Console Dashboard, click <user name> at the top right of the page and then
click Configure Console. Locate the Header frame.

2 Click the Roles and Tasks view or the Access Manager view .

1.1.2 Setting a Permanent Default View

1 In Administration Console Dashboard, click <user name> at the top right of the page and then
click Change Preferences.
2 In the left navigation frame, click Set Initial View.
3 Select your preferred view and click OK.

1.2 Managing Administration Console Session Timeout

The web.xml file for Tomcat specifies how long an Administration Console session can remain
inactive before the session times out and the administrator must authenticate again. The default
value is 30 minutes.
Perform the following steps to change this value:
1 Change to the Tomcat configuration directory:
Linux: /opt/novell/nam/adminconsole/conf/web.xml
Windows Server 2012: \Program Files\Novell\Tomcat\conf
2 Open the web.xml file in a text editor and search for the <session-timeout> parameter.
3 Modify the value and save the file.
4 Restart Tomcat:
Linux: /etc/init.d/novell-ac restart OR rcnovell-ac restart
Windows: net stop Tomcat8
net start Tomcat8

Configuring Administration Console 29

 1.3 Managing Administrators
You can create administrators with different access controls manage them in Administration
Console.
Administration Console notifies you when another administrator makes changes to a policy
container or to an Access Manager device such as an Access Gateway. The person who is currently
editing the configuration is listed at the top of the page with an option to unlock and with the
person’s distinguished name and IP address. If you select to unlock, you destroy all changes the
other administrator has done.

WARNING: Locking has not been implemented on the pages for modifying Identity Server. If you
have multiple administrators, they need to coordinate with each other so that only one
administrator is modifying an Identity Server cluster at any given time.

Multiple Sessions: Do not start multiple sessions of Administration Console in the same browser on
a workstation. Browser sessions share settings that can result in problems when you apply changes
to configuration settings. However, if you are using two different brands of browsers simultaneously,
such as Internet Explorer and Firefox, it is possible to avoid the session conflicts.
Multiple Administration Consoles: As long as the primary console is running, all configuration
changes must be made at the primary console. If you make changes at both a primary console and a
secondary console, browser caching can cause you to create an invalid configuration.
The following sections explain how to create additional administrator accounts, how to delegate
rights to administrators, and how to manage policy view administrators:
 Section 1.3.1, “Creating Multiple Admin Accounts,” on page 30
 Section 1.3.2, “Managing Policy View Administrators,” on page 31
 Section 1.3.3, “Managing Delegated Administrators,” on page 31
 Section 1.3.4, “Changing Administrator’s Password,” on page 36

1.3.1 Creating Multiple Admin Accounts

Administration Console is installed with one admin user account. If you have multiple
administrators, you might want to create a user account for each one so that log files reflect the
modifications done by each administrator. The easiest way to do this is to create a new user as a
trustee of the tree root with [Entry Rights] for Supervisor and inheritable rights assignment This also
ensures that you have more than one user who has full access to Administration Console. If you have
only one administrator user and the user forgets the password, you cannot access Administration
Console.
To create a new user as a trustee of the tree root:
1 In Administration Console Dashboard, click <user name> and then click Manage Roles & Tasks.
2 Click Users > Create User.
Specify all required details to create a valid user.

NOTE: Select the same Context that the existing administrator has. For example, novell.

30 Configuring Administration Console

 3 Click Rights > Modify Trustees, then select the tree root user.
4 Add the newly created user as a trustee of the tree root user.
5 Click Assigned Rights and specify [Entry Rights] for supervisor and inheritable rights assignment.
6 Click Done.

You can also create delegated administrators and grant them rights to specific components of Access
Manager. For information about how to configure this type of user, see Section 1.3.3, “Managing
Delegated Administrators,” on page 31.

1.3.2 Managing Policy View Administrators

The super administrators can create policy view administrators. Policy view administrators can log in
to Access Manager with their credentials and they can only view the policy containers assigned to
them.
The policy view administrators are created same as creating users. For more information, see
“Creating Users” on page 35. In Step 7b, select "ou=policyviewusers, o=novell” option in Context.
After creating user, assign rights to the newly created user. For more information, see “Policy
Container Administrators” on page 33.

1.3.3 Managing Delegated Administrators

As an Access Manager administrator, you can create delegated administrators to manage the
following Access Manager components.
 Individual Access Gateways or an Access Gateway cluster
 Identity Server clusters
 Policy containers

IMPORTANT: You need to trust the users you assign as delegated administrators. They are granted
sufficient rights that they can compromise the security of the system. For example if you create
delegated administrators with View/Modify rights to policy containers, they have sufficient rights to
implement a cross-site scripting attack by using the Deny Message in an Access Gateway
Authorization policy.
Delegated administrators are also granted rights to the LDAP server. They can access the
configuration datastore with an LDAP browser. Any modifications made with the LDAP browser are
not logged by Access Manager.

By default, all users except the administrator are assigned no rights to the policy containers and the
devices. The administrator has all rights and cannot be configured to have less than all rights. The
administrator is the only user who has the rights to delegate rights to other users, and the only user
who can modify keystores, create certificates, and import certificates.
The configuration pages for delegated administrators control access to the Access Manager pages.
They do not control access to the tasks available for the Manage Roles & Tasks view in iManager. If
you want your delegated administrators to have rights to any of these tasks such as Directory
Administration or Groups, you must use eDirectory methods to grant the user rights to these tasks or
enable and configure Role-Based Services in iManager.

Configuring Administration Console 31

 To create a delegated administrator, you must first create user accounts, then assign them rights to
the Access Manager components.
1 In Administration Console Dashboard, click <user name> at the top right of the page and then
click Manage Roles & Tasks.
2 (Optional) If you want to create a container for your delegated administrators, click Directory
Administration > Create Object, then create a container for the administrators.
3 To create the users, click Users > Create User and create user accounts for your delegated
administrators. You can create the users based on the delegatedusers or policyviewusers
context. For more information, see “Creating Users” on page 35.
4 In Administration Console Dashboard, click <user name> at the top right of the page and then
click Administrators in the Dashboard.
5 Select the component you want to assign a user to manage.
For more information about the types of rights you might want to assign for each component,
see the following:
 “Access Gateway Administrators” on page 33
 “Policy Container Administrators” on page 33
 “Delegated Administrators of Identity Servers” on page 35
6 To assign all delegated administrators the same rights to a component, configure All Users
option by using the drop-down menu and selecting None, View Only, or View/Modify.
By default, All Users is configured for None. All Users is a quick way to assign everyone View Only
rights to a component when you want your delegated administrators to have the rights to view
the configuration but not change it.
7 To select one or more users to assign rights, click Add, then specify the following details:
Name filter: Specify a string that you want the user’s cn attribute to match. The default value is
an asterisk, which matches all cn values.
Search from context: Specify the context you want used for the search. Click the down-arrow to
select from a list of available contexts.
Include subcontainers: Specifies whether subcontainers must be searched for users.
8 Click Query. The User section is populated with the users that match the query.
9 In the User section, select one or more users to whom you want to grant the same rights.
10 For the Access option, click the down-arrow and select one of the following values:
View/Modify: Grants full configuration rights to the device. View/Modify rights do not grant
the rights to manage keystores, to create certificates, or to import certificates from other
servers or certificate authorities. View/Modify rights allow the delegated administrator to
perform actions such as stop, start, and update the device.
If the assignment is to a policy container, this option grants the rights to create policies of any
type and to modify any existing policies in the container
View Only: Grants the rights to view all the configuration options of the device or all rules and
conditions of the policies in a container.
None: Prevents the user from seeing the device or the policy container.
11 In the Device or Policy Containers section, select the devices, the clusters, or policy containers
that you want to assign for delegated administration.

32 Configuring Administration Console

 12 Click Apply.
The rights are immediately assigned to the selected users. If the user already had a rights
assignment to the device or policy container, this new assignment overwrites any previous
assignments.
13 After assigning a user rights, check the user’s effective rights.
A user’s effective rights and assigned rights do not always match. For example, if Kim is granted
View Only rights but All Users have been granted View/Modify rights, Kim’s effective rights are
View/Modify.

1.3.3.1 Access Gateway Administrators

You can assign a user to be a delegated administrator of an Access Gateway cluster or a single Access
Gateway that does not belong to a cluster. You cannot assign a user to manage a single member of a
cluster.
When a delegated administrator of an Access Gateway cluster is granted View/Modify rights, the
administrator has sufficient rights to change the cluster configuration, to stop and start (or reboot
and shut down), and to update Access Gateways in the cluster. However, to configure Access
Gateway to use SSL, you need to be the admin user, rather than a delegated administrator.
When the user is assigned View/Modify rights to manage a cluster or an Access Gateway, the user is
automatically granted View Only rights to the master policy container. If you have created other
policy containers, these containers are hidden until you grant the delegated administrator rights to
them. View Only rights allows the delegated administrator to view the policies and assign them to
protected resources. It does not allow them to modify the policies. If you want the delegated
administrator to modify or create policies, you need to grant View/Modify rights to a policy
container.
View/Modify rights to an Access Gateway or a cluster allows the delegated administrator to modify
which Identity Server cluster Access Gateway uses for authentication. It does not allow delegated
administrators to update Identity Server configuration, which is required whenever Access Gateway
is configured to trust an Identity Server. To update Identity Server, the delegated administrator needs
View/Modify rights to Identity Server configuration.

1.3.3.2 Policy Container Administrators

The policy container administrators are of two types:
 Delegated Administrators
 Policy View Administrators

Delegated Administrators
All delegated administrators with View/Modify rights to a device have read rights to the master
policy container. To create or modify policies, a delegated administrator needs View/Modify rights to
a policy container. When a delegated administrator has View/Modify rights to any policy container,
the delegated administrator is also granted enough rights to allow the administrator to select shared
secret values, attributes, LDAP groups, and LDAP OUs to policies.

Configuring Administration Console 33

 If you want your delegated administrators to have full control over a device and its policies, you
might want to create a separate policy container for each delegated administrator or for each device
that is managed by a group of delegated administrators.
Policy View Administrators
A policy view administrator has rights only to view policy containers. The super administrators can
create a special type of delegated administrators called policy view administrators. The policy view
administrators can log in to Access Manager with their credentials and they are allowed to view only
the policy containers assigned to them.
Using Policy Container option, the super administrators can add and remove the delegated and
policy view administrators.
 Adding Administrators
 Removing Administrators

Adding Policy Container Administrators

The administrator can assign the rights to the delegated administrators and the users based on the
policy containers.
1 In Administration Console Dashboard, click <user name> at the top right of the page and then
click Administrators > Policy Containers > Add Administrators.
2 (Optional) Specify the filter.
3 Select the Access Rights from the list for the type of administrator. For Example -View/Modify,
View Only, and None. The policy view administrators have only View Only rights.
4 Select the search from context in the list. For example, “ou=delegated users, o=novell,
ou=policyviewusers, o=novell”. Based on the user selected, the delegated or policy view
administrators are created.
5 (Optional) Select Include Subcontainers, if you want to add it.
6 Click Query. The users and the policy containers are displayed for the selected query.
7 Select User and Policy Container. The users and policy containers list are displayed based on the
association with query.
8 Click Apply > Close.

Removing Policy Container Administrators

1 In Administration Console Dashboard, click <user name> at the top right of the page and then
click Administrators > Policy Containers > Remove Administrators.
2 Select the check box of the user assigned to the administrator and click Remove.
3 Click Close.

34 Configuring Administration Console

1.3.3.3 Delegated Administrators of Identity Servers
You cannot assign a delegated administrator to an individual Identity Server. You can only assign a
delegated administrator to a cluster configuration, which gives the delegated administrator rights to
all the cluster members.
When a delegated administrator of an Identity Server cluster is granted the View/Modify rights, the
administrator has sufficient rights to change the cluster configuration and to stop, start, and update
Identity Servers in that cluster. The administrator is granted view rights to the keystores for each
Identity Server in the cluster. To change any of the certificates, the administrator needs to be the
admin user rather than a delegated administrator.
The delegated administrator of an Identity Server cluster is granted View Only rights to the master
policy container. If you want the delegated administrator with View/Modify rights to have sufficient
rights to manage policies, grant the following rights:
 To have sufficient rights to create Role policies, grant View/Modify rights to a policy container.
 To have sufficient rights to enable Role policies, grant View Only rights to the policy containers
with Role policies.

1.3.3.4 Creating Users

After creating users, you can assign the role of a delegated administrator or policy view
administrator.
1 Log in to Access Manager.
2 In Administration Console Dashboard, click <user name> at the top right of the page and then
click Manage Roles & Tasks > Users > Create User.
3 User Name: Specify the user name. This is a mandatory field.
4 (Optional) First Name: Specify the first name of the user.
5 Last Name: Specify the name of the delegated administrator user. This is a mandatory field.
6 (Optional) Full Name: Specify the full name of the user.
7 Context: Specify the context as delegated administrators.This is a mandatory field.
7a Click object selector icon. The object selector browser displays the Browse and Search tabs.
7b Click Browse tab. Select delegated users option from the Contents list. The
delegatedusers.novell or policyviewusers.novell is displayed in the context field based on
the selection.
8 Password: Specify the password and retype the password to confirm it.

NOTE: Failure to enter a password will allow the user to login without a password.

9 (Optional) Simple Password: Select this check box to set the simple password.

NOTE: Simple Password is required for native file access on Windows and Macintosh using the
CIFS and AFP protocols. Simple Password is not required for normal eDirectory access. The
Universal Password feature supersedes Simple Password. When the Universal Password feature

Configuring Administration Console 35

 is enabled, setting the Simple Password is not required. For more information about the
Universal Password feature, see Netware 6.5 Documentation. (http://www.novell.com/
documentation/nw65/?page=/documentation/lg/nw65/universal_password/data/front.html)

10 (Optional) Copy from Template or User Object: Copies the attributes from a user template that
you've created.
11 (Optional) Create Home Directory: You can create a home directory for this new User object if
you have sufficient eDirectory rights. To do this, specify the path where you want to create the
user's home directory.
11a Volume: Applies only to NCP-enabled volumes.
11b Path: You must specify a valid, existing directory path.The last directory typed in the path is
the one that is created; all other directories in the path must already exist. For example, if
you specify the path corp/home/sclark, the directories corp and home must already exist.
The directory sclark is the only directory created.
12 (Optional) Enter or Select the title, location, department, telephone number, fax number, email
address of the delegated user from the list.
13 (Optional) Enter the description if there are any to the user. You are able to add, remove and
edit the information as per the requirement.
14 Click OK.

After creating a user, assign rights to the newly created user. For more information, see “Policy
Container Administrators” on page 33.

1.3.4 Changing Administrator’s Password

You can change password of Administration Console and user store’s administrators.
 Section 1.3.4.1, “Changing the Password of Administration Console Administrator,” on page 36
 Section 1.3.4.2, “Changing the Administration Password of the User Store Administrator,” on
page 37

NOTE: The password is not case-sensitive by default. To make your password case-sensitive, see
Enforcing Case-Sensitive Universal Passwords (https://www.netiq.com/documentation/edirectory-
91/edir_admin/data/b1j691df.html).

1.3.4.1 Changing the Password of Administration Console Administrator

1 In Administration Console Dashboard, click <user name> at the top right of the page and then
click Manage Roles & Tasks. Click Users > Modify User.
2 Click the Object Selector icon.
3 Browse to the novell container and select the name of the admin user, then click OK.
4 Click Restrictions > Set Password.
5 Specify a password in New password and confirm the password in Retype new password.
6 Click OK > OK.

36 Configuring Administration Console

1.3.4.2 Changing the Administration Password of the User Store Administrator
Perform the following steps to change the admin password of a user store configured for Identity
Server:
1 Click Devices > Identity Servers > <Cluster>.
2 Go to the Local tab and click the existing user store name in the user store’s list.
3 Enter a password that matches the User Store password
4 Click Apply.

1.4 Changing the IP Address of Access Manager Devices

The following sections explain how to change the IP address on the following devices:
 Section 1.4.1, “Changing the IP Address of Administration Console,” on page 37
 Section 1.4.2, “Changing the IP Address of Identity Server,” on page 37
 Section 1.4.3, “Changing the IP Address of Access Gateway Appliance,” on page 39
 Section 1.4.4, “Changing the IP Address of Access Gateway Service,” on page 40
 Section 1.4.5, “Changing the IP Address of Audit Server,” on page 41

1.4.1 Changing the IP Address of Administration Console

Install Administration Console with the IP address that it will always use. All devices that are import
into Administration Console use this IP address to establish secure communication with
Administration Console.
The only tested method of changing the IP address so that all other devices trust Administration
Console is to install a secondary console with the new IP address and then promote the secondary
console to be the primary console.
See the following sections:
 Section 11.1, “Installing Secondary Administration Console,” on page 973
 “Converting a Secondary Administration Console into a Primary Console” on page 1266

Converting a secondary console into a primary console is designed as a disaster recovery solution
when the primary console is no longer available.

1.4.2 Changing the IP Address of Identity Server

These instructions assume that your Identity Server and Administration Console are not on the same
machine. If they are on the same machine, see Section 1.4.1, “Changing the IP Address of
Administration Console,” on page 37.
Perform the following steps to move a machine or change the IP address for Identity Server:
1 Click Devices > Identity Servers.
2 Select the Identity Server for which you require to change the IP address.

Configuring Administration Console 37

 3 Click Stop.
4 Select the same Identity Server and click Actions > Remove from Cluster.
5 Select the same Identity Server and click Actions > Delete.
6 On Identity Server, stop the server communication service by using the following command:
Linux: /etc/init.d/novell-jcc stop OR rcnovell-jcc stop
Windows: net stop jccserver
7 Change the IP address by using an operating system utility:
Linux: Click YaST > Network Devices > Network Card, select a method, select the card, and click
Edit.
Windows: Click Control Panel > Network Connections > Local Area Connection > Properties >
Internet Protocol (TCP/IP) > Properties.
8 Change to the jcc directory:
Linux: /opt/novell/devman/jcc
Windows: \Program Files\Novell\devman\jcc
9 Run the configure command:
Linux: conf/Configure.sh
Windows: conf\configure.cmd
The command must be run from the jcc directory because it needs access to files that are
available from this directory.
10 When prompted for the local listener IP address, specify the new IP address.
11 When prompted for the administration server IP, specify the IP address of Administration
Console.
12 Follow the prompts and accept the defaults for ports and admin user.
13 Replace all references to the old IP address in the server.xml file with the new IP address:
13a Change to the Tomcat configuration directory:
Linux: /opt/novell/nam/idp/conf
Windows: \Program Files\Novell\Tomcat\conf
13b In a text editor, open the server.xml file.
13c Search for the old IP address and replace it with the new IP address.
13d Save your changes.
14 Start the server communication service by using the following command:
Linux: /etc/init.d/novell-jcc start OR rcnovell-jcc start
Windows: net start jccserver
15 Restart Tomcat:
Linux: Run the following command:
/etc/init.d/novell-idp restart OR rcnovell-idp restart
Windows: Run the following commands:
net stop Tomcat8
net start Tomcat8

38 Configuring Administration Console

 16 Reimport Identity Server with the new IP address into Administration Console.
16a On the Identity Server machine, change to the jcc directory:
Linux: /opt/novell/devman/jcc
Windows: \Program Files\Novell\devman\jcc
16b Run the reimport script for jcc:
Linux: ./conf/reimport_nidp.sh jcc
Windows: conf\reimport_nidp.bat jcc
16c Run the reimport script for Administration Console:
Linux: ./conf/reimport_nidp.sh nidp
Windows: conf\reimport_nidp.bat nidp <admin>
16d Replace <admin> with the name of your Administration Console administrator.

NOTE: If these steps do not work, see “Troubleshooting Identity Server Import and
Installation” in the NetIQ Access Manager 4.5 Installation and Upgrade Guide.

16e Add reimported Identity Server to the cluster.

1.4.3 Changing the IP Address of Access Gateway Appliance

To change the IP address of Access Gateway machine, you need to configure Access Gateway for this
change. This is especially significant when Access Gateway Appliance has only one IP address.

IMPORTANT: The new IP address must be configured in Administration Console before you change it
on Access Gateway. If you change the address on Access Gateway first, Administration Console does
not trust Access Gateway and cannot establish the communication.

1 Click Devices > Access Gateways > Edit > Adapter List.
2 (Conditional) If the machine belongs to a cluster, select Access Gateway from the Cluster
Member list.
3 From the Adapter List, select the subnet mask that contains the IP address you want to change.
4 Select the old IP address, click Change IP Address, specify the new IP address, then click OK.
This option changes all configuration instances of the old IP address to the new IP address. For
example, any reverse proxies that have been assigned the old IP address as a listening address
are modified to use the new IP address as the listening address.
5 Click OK.
6 To apply your changes, click the Access Gateways link, then click Update > OK.
7 If you are physically moving the machine, move it before completing the rest of these steps.
8 Check the IP address that Administration Console uses for managing Access Gateway. Click
Access Gateways > [Name of Access Gateway] > Edit.
9 If the old IP address is listed as the Management IP Address, select the new IP address. If your
Access Gateway has multiple IP addresses, select the one that you want Administration Console
to use for communication with Access Gateway.

Configuring Administration Console 39

 The port must only be modified if there is another device on Access Gateway that is using the
default port of 1443.
10 If the name of Access Gateway is the old IP address, modify the Name option.
11 Click OK.
Administration Console uses the configured IP address to find Access Gateway.
12 On Access Gateway server, restart Tomcat:
Linux: /etc/init.d/novell-mag restart OR rcnovell-mag restart
Windows: Run the following commands:
net stop Tomcat8
net start Tomcat8
If your Access Gateway stops reporting to Administration Console after completing these steps,
trigger an auto-import. See “Triggering an Import Retry” in the NetIQ Access Manager 4.5
Installation and Upgrade Guide.

1.4.4 Changing the IP Address of Access Gateway Service

1 On Access Gateway Service, use a system utility to add the new IP address.
Do not delete the old IP address at this time.
Linux: Start YaST, click Network Devices > Network Card, then select the Traditional Method.
Windows: Access the Control Panel, click Network Connections > Local Area Connection >
Properties, then select Internet Protocol (TCP/IP). Click Properties > Advanced.
2 In Administration Console, import the new IP address:
2a Click Access Gateways > [Name of Access Gateway] > New IP.
2b Click OK.
Wait for the command to complete.
3 Change the management IP address:
3a On the Server Details page, click Edit.
3b If the old IP address is listed as the Management IP Address, select the new IP address.
If your Access Gateway has multiple IP addresses, select the one that you want
Administration Console to use for communication with Access Gateway.
3c (Conditional) Modify the port if there is another device on Access Gateway that is using the
default port of 1443.
3d If the name of Access Gateway is the old IP address, modify the Name option.
3e Click OK.
Administration Console uses the configured IP address to find Access Gateway.
4 To verify that the new IP address is being used, check the health of Access Gateway.
5 Edit Access Gateway configuration so that the reverse proxies use the new IP address:
You need to complete these steps for each reverse proxy.
5a Click Access Gateways > Edit > [Name of Reverse Proxy].
5b (Conditional) If a member of a cluster, select the cluster member that has a new IP address.

40 Configuring Administration Console

 5c For the listening address, deselect the old IP address and select the new IP address.
5d Apply the settings and update Access Gateway.
5e Verify that everything is working correctly by accessing a resource protected by this reverse
proxy.
6 On Access Gateway Service machine, use a system utility to remove the old IP address.
7 Remove the old IP address from Administration Console:
7a Click Access Gateways > [Name of Access Gateway] > New IP.
7b Click OK.
Wait for the command to complete.
7c To verify that the old address has been removed, click Edit and verify that the old address is
not an option for the Management IP Address.

1.4.5 Changing the IP Address of Audit Server

1 In Administration Console Dashboard, click Auditing.
2 Change the IP address for the server and, if necessary, the port.
3 Click OK.
4 Update all Access Gateways.

1.5 Mapping the Private IP Address to Public IP Address

Use Global Settings to configure mapping of Administration Console private IP address to public NAT
IP address.
Devices that cannot reach the private Administration Console IP address use the NAT IP address. You
must specify the NAT IP addresses prior to importing devices.
You can perform the following activities by using Global Settings:
 Section 1.5.1, “Creating a New NAT IP Address Mapping,” on page 41
 Section 1.5.2, “Removing a NAT IP Address Mapping,” on page 42
 Section 1.5.3, “Viewing the NAT IP Address Mapping,” on page 42
 Section 1.5.4, “Editing a NAT IP Address Mapping,” on page 42

1.5.1 Creating a New NAT IP Address Mapping

1 In Administration Console Dashboard, click <user name> at the top right of the page and then
click Global Settings > New.
2 Select an IP address from the Administration Console Public IP Address list.
3 Specify the Public NAT IP Address.

NOTE: If NAT IP address is not provided or if a mapping already exists for the selected
Administration Console IP, this message is displayed:

Configuring Administration Console 41

 IP Address is not valid

4 Click OK > Apply Changes.

5 Click Cancel to exit.

1.5.2 Removing a NAT IP Address Mapping

1 In Administration Console Dashboard, click <user name> icon at the top right of the page and
then click Global Settings
2 Select the IP address you want to delete.
3 Click Delete > OK.

1.5.3 Viewing the NAT IP Address Mapping

1 In Administration Console Dashboard, click <user name> at the top right of the page and then
click Global Settings. You can see the list of already configured physical IP addresses and NAT IP
addresses.
2 Create New if the list does not contain any Physical IP Address and NAT IP Address entries.
Physical IP Address: Specifies the physical private IP Address for Administration Console.
Public NAT IP Address: Specifies the Public NAT IP Address. You can configure or map the NAT IP
Address.
3 Click Close.

1.5.4 Editing a NAT IP Address Mapping

1 In Administration Console Dashboard, click <user name> at the top right of the page and then
click Global Settings.
2 Click Public NAT IP Address.
3 Specify the new Public NAT IP Address.

4 Click OK.

42 Configuring Administration Console

2 Setting Up a Basic Access Manager
2

Configuration
The initial setup for Access Manager consists of setting up Identity Server and Access Gateway to
protect resources running on an HTTP web server. You must set up user stores for Identity Server and
configure Access Gateway to protect resources running on an HTTP web server.
 Section 2.1, “Prerequisites for a Basic Access Manager Setup,” on page 43
 Section 2.2, “Configuring Identity Servers Clusters,” on page 44
 Section 2.3, “Configuring Identity Server Shared Settings,” on page 62
 Section 2.4, “Configuring Access Gateway,” on page 106
 Section 2.5, “Configuring Access Gateways Clusters,” on page 113
 Section 2.6, “Protecting Web Resources Through Access Gateway,” on page 120
 Section 2.7, “Configuring Trusted Providers for Single Sign-On,” on page 184
 Section 2.8, “Configuring Single Sign-On to Specific Applications,” on page 216
 Section 2.9, “Configuring a Protected Identity Server Through Access Gateways,” on page 239
 Section 2.10, “Managing Access to User Portal,” on page 246
 Section 2.11, “Sample Configuration for Protecting an Application Through Access Manager,” on
page 251

2.1 Prerequisites for a Basic Access Manager Setup

 Access Manager version of iManager (Access Manager Administration Console) is installed.
 An Identity Server is installed.
 An Access Gateway is installed.
 An LDAP directory store with a test user added. This store can be eDirectory, Active Directory, or
Sun ONE.
 A DNS server or modified host files to resolve DNS names and provide reverse lookups. For
information about the host files that need to be modified, see “Configuring Name Resolution”
on page 255.

Setting Up a Basic Access Manager Configuration 43

  A web server (IIS or Apache). The web server must have three directories with three HTML
pages. The first directory (public) must contain a page (such as index.html) for public access.
This page needs to provide two links:
 A link to a page in the protected directory. You will configure Access Gateway to require
authentication before allowing access to this page. You do not need to configure the web
server to protect this page.
 A link to a page in the basic directory. You must already have configured your web server
to require basic authentication before allowing access to this page. See your web server
documentation for instructions on setting up basic authentication. (This type of access is
optional, but explained because it is fairly common.)
If you do not have a web server that you can use for this type of access, you might prefer to
configure Access Manager for the sample web pages we provide. See Chapter 2.11, “Sample
Configuration for Protecting an Application Through Access Manager,” on page 251.
 A client workstation with a browser with browser pop-ups enabled.

2.2 Configuring Identity Servers Clusters

After you install an Identity Server, you must create a cluster configuration to configure Identity
Server. When you create a cluster, ensure that the servers are installed on the same operating
system. 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 2-1.
Figure 2-1 Identity Server Configurations

Configuration A Configuration A Configuration B

Identity Server 1 Identity Server 1

Identity Server 2 Identity Server 2

A cluster of Identity Servers must reside behind a Layer 4 (L4) switch. Clients access the virtual IP
address of the cluster presented on the L4 switch, and the L4 switch alleviates server load by
balancing traffic across the cluster. If your Identity Server is on the same machine as an
Administration Console, and your second Identity Server is on the same machine as a secondary
Administration Console, ensure that you are familiar with Section 11.1, “Installing Secondary
Administration Console,” on page 973 before proceeding.
Whenever a user accesses the virtual IP address (port 8080) assigned to the L4 switch, the system
routes the user to one of Identity Servers in the cluster, as traffic necessitates.

44 Setting Up a Basic Access Manager Configuration

 The system automatically enables clustering when multiple Identity Servers exist in a group. If only
one Identity Server exists in a group, clustering is disabled.

IMPORTANT: You must not use a DNS round robin setup instead of an L4 switch for load balancing.
The DNS solution works only as long as all members of the cluster are working and in a good state. If
one of them goes down and traffic is still sent to that member, the entire cluster is compromised and
all devices using the cluster start generating errors.

This section describes how to set up and manage a cluster of Identity Servers:
 Section 2.2.1, “Configuration Notes,” on page 45
 Section 2.2.2, “Prerequisites for Configuring an Identity Servers Cluster,” on page 46
 Section 2.2.3, “Managing a Cluster of Identity Servers,” on page 47

2.2.1 Configuration Notes

 Section 2.2.1.1, “Services of the Real Server,” on page 45
 Section 2.2.1.2, “A Note about Service Configuration,” on page 45
 Section 2.2.1.3, “A Note about Alteon Switches,” on page 46

2.2.1.1 Services of the Real Server

A user’s authentication remains on the real (authentication) server cluster member that originally
handled the user’s authentication. If this server malfunctions, all users whose authentication data
resides on this cluster member must re-authenticate unless you have enabled session failover. For
more information about this feature, see “Configuring Session Failover” on page 53.
Requests that require user authentication information are processed on this server. When the
system identifies a server as not being the real server, the HTTP request is forwarded to the
appropriate cluster member, which processes the request and returns it to the requesting server.

2.2.1.2 A Note about Service Configuration

If your L4 switch can perform both SSL and non-SSL health checks, you must configure the L4 switch
only for the services that you are using in your Access Manager configuration. For example, if you
configure the SSL service and the non-SSL service on the L4 and the base URL of your Identity Server
configuration is using HTTP rather than HTTPS, the health check for the SSL service fails. The L4
switch then assumes that all Identity Servers in the cluster are down. Therefore, ensure that you
enable only the services that are also enabled on Identity Server.

Setting Up a Basic Access Manager Configuration 45

2.2.1.3 A Note about Alteon Switches
When you configure an Alteon switch for clustering, direct communication between real servers
must be enabled. If direct access mode is not enabled when one of the real servers tries to proxy
another real server, the connection fails and times out.
To enable direct communication on the Alteon:
1 Go to cfg > slb > adv > direct.
2 Specify e to enable direct access mode.

With some L4 switches, you must configure only the services that you are using. For example, if you
configure the SSL service for the L4 switch and you have not configured SSL in Access Manager, then
the HTTP service on the L4 switch does not work. If the health check for the SSL service fails, the L4
switch assumes that all the services configured to use the same virtual IP are down.

2.2.2 Prerequisites for Configuring an Identity Servers Cluster

 An L4 server is installed. You can use the same server 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.
 Persistence (sticky) sessions enabled on the L4 server. You usually define this at the virtual
server level.
 An Identity Server configuration is created for the cluster. Assign all Identity Servers to this
configuration. See “Configuring Identity Servers Clusters” on page 44 for information about
creating an Identity Server configuration. See “Creating a Cluster Configuration” on page 47for
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 balances the load between Identity Servers in the cluster.
 Ensure that the L4 administration server using port 8080 has the following ports open:
 8443 (secure Administration Console)
 7801 (TCP)
 636 (for secure LDAP)
 389 (for clear LDAP, loopback address)
 524 (network control protocol on the L4 machine for server communication)
Identity Server ports must also be open:
 8080 (non-secure login)
 8443 (secure login)
 1443 (server communication)
If you are using introductions (see “Creating a Cluster Configuration” on page 47), configure the
L4 switch to load balance on ports 8445 (identity provider) and 8446 (identity consumer).

46 Setting Up a Basic Access Manager Configuration

 2.2.3 Managing a Cluster of Identity Servers
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 here. 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 2.2.3.1, “Creating a Cluster Configuration,” on page 47
 Section 2.2.3.2, “Assigning an Identity Server to a Cluster Configuration,” on page 51
 Section 2.2.3.3, “Configuring a Cluster with Multiple Identity Servers,” on page 51
 Section 2.2.3.4, “Configuring Session Failover,” on page 52
 Section 2.2.3.5, “Editing Cluster Details,” on page 53
 Section 2.2.3.6, “Removing a Server from a Cluster Configuration,” on page 54
 Section 2.2.3.7, “Enabling and Disabling Protocols,” on page 55
 Section 2.2.3.8, “Modifying the Base URL,” on page 55
 Section 2.2.3.9, “Configuring Identity Server Global Options,” on page 56

2.2.3.1 Creating a Cluster Configuration

Identity Server functions as an identity provider. You can configure it to run as an identity consumer
(also known as a service provider) by using federation protocols.
In an Identity Server configuration, you specify the following information:
 The DNS name for Identity Server or clustered server site.
 Certificates for Identity Server.
 Organizational and contact information for the server that is published in the metadata of
Liberty and SAML protocols.
 LDAP directories (user stores) to authenticate users, and trusted root for secure communication
between Identity Server and a user store.
Perform the following steps to create an Identity Server cluster:
1 Click Devices > Identity Servers.
2 Under the Servers tab, select Identity Server, and then click New Cluster.
Selecting the server is one way to assign it to the cluster configuration.
3 Specify a name for the cluster configuration.
If you did not select the server in the previous step, you can now select required servers.
For more information about assigning servers to a configuration, see “Assigning an Identity
Server to a Cluster Configuration” on page 51.
4 Click OK.

Setting Up a Basic Access Manager Configuration 47

 5 Specify the following details:

Field Description

Name Specify a name for the cluster. 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 Identity Server. Identity Server protocols rely on this
base URL to generate URL endpoints for each protocol.
 Protocol: Select the communication protocol. Specify HTTPS to run securely (in
the SSL mode) and for provisioning. Use HTTP only if you do not require security
or have installed an SSL terminator in front of Identity Server.
 Domain: Specify the DNS name assigned to Identity Server. When you are using
an L4 switch, this DNS name must resolve to the virtual IP address set up on the
L4 switch for Identity Servers. Using an IP address is not recommended.
 Port: Default ports are 8080 for HTTP or 8443 for HTTPS. If you want to use port
80 or 443, specify the port here.
 On Linux, configure the operating system to translate the port. See
Translating Identity Server Configuration Port in the NetIQ Access Manager
4.5 Installation and Upgrade Guide.
 On Windows, modify the Tomcat server.xml file located in the
\Program Files\Novell\Tomcat\conf directory for Windows.
Change the ports from 8080 and 8443 to 80 and 443 and restart the Tomcat
service.
 Application: Specify Identity Server application. Leave the default value nidp.

SSL Displays the currently assigned SSL certificate.

Certificate
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 Identity Server. You must restart Tomcat whenever you assign an
Identity Server to a configuration and whenever you update a certificate key store. See
“Managing the Keys, Certificates, and Trust Stores” on page 994.

For information about how to replace the test-connector certificate, see

Chapter 19, “Enabling SSL Communication,” on page 1071.

6 To configure session limits, specify the following details:

Field Description

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

48 Setting Up a Basic Access Manager Configuration

 Field Description

Default Specify the session timeout you want assigned as a default value when you create a
Timeout contract. This value is also assigned to a session when Identity Server cannot
associate a contract with the authenticated session. During federation, if the
authentication request uses a type rather than a contract, Identity Server cannot
always associate a contract with the request.

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

To limit user sessions, you must also consider 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 you enable this option, it affects performance in a cluster with multiple
Identity Servers. When a user is limited to a specific number of sessions, Identity
Servers must check with the other servers before establishing a new session.

Deleting You can configure Identity Server to delete the previous user sessions if the number
Previous User of open sessions reaches the maximum limit of allowed sessions that you have
Sessions specified in Limit User Sessions. Set the DELETE OLD SESSIONS OF USER
option to true and restart Identity Server. For information about how to configure
this option, see “Configuring Identity Server Global Options” on page 56. Previous
sessions are cleared across Identity Server clusters only when a fresh authentication
request comes in. When Identity Server deletes previous user sessions, it sends a
logout request to the service provider through the SOAP back channel.

For example, a user is accessing a protected resource from a machine and wants to
access the same protected resource from another device. Identity Server will not
give access to the user if the Limit User Sessions has reached a maximum limit.
Identity Server must terminate the old session of the user so that the user can
access the new session seamlessly.

Allow multiple Specify whether a user with more than one session to the server is presented with
browser an option to log out of all sessions. If you do not select this option, only the current
session logout 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, specify the following details:

Setting Up a Basic Access Manager Configuration 49

 Field Description

LDAP Specify the duration (in seconds) that an LDAP request to the user store can take before
timing out.

Proxy Specify the duration (in seconds) that 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 the duration (in seconds) that an HTTP request to an application can take before
timing out.

8 Select the required protocols.

IMPORTANT: Enable only the required protocols.

If you are using Access Gateway, you must select the Liberty protocol. Else, the trusted
relationship of Access Gateway and Embedded Service Provider with Identity Server is disabled,
and authentication fails.

 Liberty: Uses a structured version of SAML to exchange authentication and data between
trusted identity providers and service providers and provides the framework for user
federation.
 SAML 1.1: Uses XML for exchanging authentication and data between trusted identity
providers and service providers.
 SAML 2.0: Uses XML for exchanging encrypted authentication and data between trusted
identity providers and service providers and provides the framework for user federation.
 WS Federation: Allows disparate security mechanisms to exchange information about
identities, attributes, and authentication.
 WS-Trust: Allows secure communication and integration between services by using
security tokens.
 OAuth & OpenID Connect: Allows Identity Server to act as an authorization server to issue
access token to a client application based on user’s grant.
9 Click Next.
10 Specify the following details:
 Name: The name of the organization.
 Display Name: The display name for the organization.
 URL: The organization’s URL for contact purposes.
Company, First Name, Last Name, Email, Telephone, and Contact Type are optional fields.

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

11 Click Next to configure the user store.

50 Setting Up a Basic Access Manager Configuration

 You must reference your own user store and auto-import the SSL certificate. See Section 4.1.1,
“Configuring Identity User Stores,” on page 384 for information about this procedure.
After you configure the user store, the system displays the new configuration on the Servers
page.
The status icons for the configuration and Identity Server must turn green. It might take several
seconds for Identity Server to start and for the system to display a green icon. If it does not, it is likely
that 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].)

2.2.3.2 Assigning an Identity Server to a Cluster Configuration

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 “Configuring a Cluster with Multiple
Identity Servers” on page 51 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 Click Devices > Identity Servers.
2 On the Servers page, select the server’s check box.
You can select all displayed servers by selecting the top-level Server check box.
3 Click Actions > Assign to Cluster.
4 Select the configuration’s check box, then click Assign.
You are prompted to restart Tomcat. The status icon for Identity Server must turn green. It
might take several seconds for Identity Server to start and for the system to display the green
icon.

2.2.3.3 Configuring 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. You can also configure the cluster
to support session failover, so that users do not need to re-authenticate when an Identity Server
goes down.
A cluster of Identity Servers must 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 Identity Servers in the cluster, as traffic necessitates.
To set up a cluster, complete the following tasks:
 Install an L4 switch. 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
Section 11.2, “Configuration Tips for the L4 Switch,” on page 976.
 Enable persistence (sticky) sessions on the L4 switch. You can define this at the virtual server
level.

Setting Up a Basic Access Manager Configuration 51

  Create an Identity Server configuration for the cluster and assign all Identity Servers to this
configuration.
 See “Creating a Cluster Configuration” on page 47 for information about creating an
Identity Server configuration.
 See “Assigning an Identity Server to a Cluster Configuration” on page 51 for information
about assigning identity servers to configurations.
 Ensure that the DNS name of the base URL for the cluster configuration resolves via DNS to the
IP address of the L4 virtual IP address. The L4 switch balances the load between Identity Servers
in the cluster.
 Ensure that the L4 administration server using port 8080 has the following TCP ports open:
 8443 (secure Administration Console)
 7801 (for back-channel communication with cluster members).
 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 2.7.2, “Configuring General Provider Settings,” on
page 187), you must configure the L4 switch to load balance on ports 8445 (identity provider)
and 8446 (identity consumer).
 Enable session failover so users do not need to re-authenticate when an Identity Server goes
down. See “Configuring Session Failover” on page 53.
 Modify the name of the cluster or edit communication details. See “Editing Cluster Details” on
page 53.

2.2.3.4 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 Identity Servers goes down, users still have
access to your site because the other Identity Server can be used for authentication. However, it
does not provide session failover. If a user has authenticated to the failed Identity Server, the 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
 An Identity Server cluster with two or more Identity Servers.
 Sufficient memory on Identity Servers to store additional authentication information. When an
Identity Server is selected to be a failover peer, Identity Server stores about 1 KB of session
information for each user authenticated on the other machine.

52 Setting Up a Basic Access Manager Configuration

  Sufficient network bandwidth for the increased login traffic. Identity Server sends the session
information to all 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 also need to send these attributes. To
configure the attributes to send, click Devices > Identity Servers > Edit > Liberty > [Name of
Service Provider] > Attributes.

Configuring Session Failover

1 Click Devices > Identity Servers.
2 Click the name of an Identity Server cluster.
3 Click the IDP Failover Peer Server Count, then select the number of failover peers for each
Identity Server.
 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 four 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
two servers being 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 must 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 slow down your network with
the additional traffic for the session information.
4 Click OK.

How Failover Peers Are Selected

The failover peers for 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 as 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 exists on a different subnet.

2.2.3.5 Editing Cluster Details

1 Click Devices > Identity Servers.
2 Click the name of the cluster configuration.
The Cluster Details page contains the following tabs:
 Details: To modify the cluster name or its settings, click Edit, then continue with Step 3.
 Health: Click to view the health of the cluster.
 Alerts: Click to view the alerts generated by members of the cluster.
 Statistics: Click to view the statistics of the cluster members.

Setting Up a Basic Access Manager Configuration 53

 3 Modify the following details as required:

Field Description

Cluster Communication Specify a communications channel over which the cluster members
Backchannel 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 can handle a request more efficiently. This back channel must
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
Identity Servers in the cluster. 7801 is the default TCP port.
 Encrypt: Encrypts the content of the messages that are sent
between cluster members.

Level Four Switch Port Configure the L4 switch to translate the port of the incoming request to
Translation 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 Identity Server is using port 8443.
 Cluster member translated port: Specify the port of the cluster
member.

IDP Failover Peer Server For configuration information, see Configuring Session Failover.
Count

4 Click OK and then update Identity Server when prompted.

2.2.3.6 Removing a Server from a Cluster Configuration

Removing an Identity Server from a configuration disassociates Identity Server from the cluster
configuration. The configuration, however, remains intact and can be reassigned later or assigned to
another server.
1 Click Devices > Identity Servers.
2 Select the server, then click Stop. Wait for the Health indicator to turn red.
3 Select the server and then choose Actions > Remove from Cluster.

For information about deleting an Identity Server, see Section 2.2.3, “Managing a Cluster of Identity
Servers,” on page 47.

54 Setting Up a Basic Access Manager Configuration

 IMPORTANT: When the cluster contains only two Identity Servers, introduce a new Identity Server
to the cluster before removing the other Identity Server.

2.2.3.7 Enabling and Disabling Protocols

You must enable a protocol and configure it before users can use the protocol for authentication. For
security purposes, you must enable only the required protocols that you will use for authentication.
After disabling a protocol, update the Identity Server configuration, and stop and start Identity
Server.
1 Click Devices > Identity Servers > Edit.
2 In the Enabled Protocols section, select the required protocols to enable.
3 To disable a protocol, deselect it.
4 Click OK.
5 (Conditional) If you have enabled a protocol, update Identity Server.
6 (Conditional) If you have disabled a protocol, stop and start Identity Server.
6a Select Identity Server and click Stop.
6b When the health turns red, select Identity Server, and click Start.
6c Repeat the process for each Identity Server in the cluster.

2.2.3.8 Modifying the Base URL

When you configure 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 re-import 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 Identity Server, you invalidate the following trusted relationships:
 The trusted relationships that Identity Server has established with each Access Manager device
that has been configured to use Identity Server for authentication
 The trusted relationship that each Access Manager device has established with Identity Server
when Identity Server configuration was selected.
 The trusted relationships that 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.
Perform the following steps to modify the base URL and reestablish trust relationships:
1 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.

Setting Up a Basic Access Manager Configuration 55

 5 Restart Tomcat on each Identity Server in the configuration:
 Linux Identity Server: Specify one of the following commands:
/etc/init.d/novell-idp restart
rcnovell-idp restart
 Windows Identity Server: Specify the following commands:
net stop Tomcat8 net start Tomcat8
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.
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
Chapter 19, “Enabling SSL Communication,” on page 1071.

2.2.3.9 Configuring Identity Server Global Options

Global options are applicable for all Identity Servers in a cluster.

NOTE: Access Manager 4.2 onwards, configuring the following options through files is deprecated.
You must configure these option by using Administration Console.

Perform the following steps to configure Identity Server global options:

1 Click Devices > Identity Servers > Edit > Options.
2 Click New.
3 Set the following properties based on your requirement:

Property Value

Allow Auth Policy Execution Select false to disable Identity Server to execute authorization
policies. The default value is true.

For example, see “Executing Authorization Based Roles Policy During

SAML 2.0 Service Provider Initiated Request” on page 514.

Cluster Cookie Domain Set this property to change the Domain attribute for Identity Server
cluster cookie.

For example, see “Configuring X.509 Authentication to Display the

Access Manager Error Message” on page 428.

Cluster Cookie Path Set this property to change the Path attribute for Identity Server
cluster cookie. The default value is /nidp.

For example, see “Configuring X.509 Authentication to Display the

Access Manager Error Message” on page 428.

56 Setting Up a Basic Access Manager Configuration

Property Value

DECODE RELAY STATE PARAM Select true to enable the relay state URL decoding. The default value
is false.

DELETE OLD SESSIONS OF Select true to enable Identity Server to delete the previous user
USER sessions if the number of open sessions reaches the maximum limit
of allowed sessions that you have specified in Limit User Sessions.
The default value is false.

HTTP ONLY CLUSTER COOKIE Select false to disable the HTTPOnly flags for Identity Server cluster
cookies. The default value is true.

For example, see Section 32.3.11, “Enabling Secure or HTTPOnly Flags

for Cluster Cookies,” on page 1319.

HTTP POPULATE LOGINNAME Select true to auto-populate the email ID on the Identity Server login
FROM SAML AUTH REQUEST page for a SAML 2.0 authentication. The default value is false.

(This option is available in For more information about this option, see “Auto-Populating the
Access Manager 4.5 Service Username on the Identity Server Login Page” on page 689.
Pack 1 or later versions)

HTTP POPULATE PARSED Select true to auto-populate the username instead of the entire email
LOGINNAME FROM SAML ID on the Identity Server login page for a SAML 2.0 authentication.
AUTH REQUEST For example, to populate steve.smith instead of
[email protected]. The default value is false.
(This option is available in
Access Manager 4.5 Service For more information about this option, see “Auto-Populating the
Pack 1 or later versions) Username on the Identity Server Login Page” on page 689.

HTTP POPULATE LOGINNAME Select true to auto-populate the email ID on the Identity Server login
FROM WSFED AUTH page for a WS-Fed authentication request. The default value is false.
REQUEST

(This option is available in

Access Manager 4.5 Service
Pack 1 or later versions)

HTTP POPULATE PARSED Select true to auto-populate the username instead of the entire email
LOGINNAME FROM WSFED ID on the Identity Server login page for a WS-Fed authentication. For
AUTH REQUEST example, to populate steve.smith instead of
[email protected]. The default value is false.
(This option is available in
Access Manager 4.5 Service
Pack 1 or later versions)

IS SAML2 POST INFLATE Select true to enable Identity Server to receive deflated SAML 2.0
POST messages from its trusted providers. The default value is false.

You can configure post binding to be sent as a compressed option by

configuring this property. For example, see the note in Step 4 on
page 518.

IS SAML2 POST SIGN Select true to enable the identity provider to sign the entire SAML 2.0
RESPONSE response for all service providers.

Setting Up a Basic Access Manager Configuration 57

 Property Value

LOGIN CSRF CHECK Select true to enable Cross-Site Request Forgery (CSRF) check for the
Password Class and TOTP Class.

This is applicable for Access Manager default pages. If you have

modified any page, you must add the CSRF token to the page. To add
the CSRF token, add the following:

JAVA:

<%
String sid = request.getParameter("sid")!=null ?
request.getParameter(NIDPConstants.SID) :
(String)request.getAttribute(NIDPConstants.SID);
NIDPSessionData sData =
NIDPContext.getNIDPContext().getSession(request).ge
tSessionData(sid);
boolean csrfCheckRequired =
NIDPEdirConfigUtil.isConfigured(NIDPConfigKeys.LOGI
N_CSRF_CHECK.name()) ?
NIDPEdirConfigUtil.getValueAsBoolean(NIDPConfigKeys
.LOGIN_CSRF_CHECK.name()) : false;
%>

HTML:

<% if (csrfCheckRequired) { %>

<input type="hidden" name="AntiCSRFToken"
value=" <%=sData.getAntiCSRFToken()%>">
<% } %>

OAUTH TOKENS IN BINARY Select true to send tokens in the binary format.
FORMAT
By default, the value is set to false and tokens are sent in the JWT
format.

It is recommended to not use this property unless you have an

existing client application that cannot manage a token larger than the
existing binary token.

NOTE: : When the value is set to true, few features, such as token
encryption using resource server keys and token revocation, will not
be available.

RENAME SESSION ID Select false to prevent changing the session ID automatically. The
default value is true.

SAML1X ATTRIBUTE MATCH Select true to perform a strict check on the name space of the
BY NAME attributes received in assertion.

For example, see Section 32.3.24, “SAML 1.1 Service Provider Re-
requests for Authentication,” on page 1325.

58 Setting Up a Basic Access Manager Configuration

Property Value

SAML2 ATTRIBUTE This option can be used to identify globally the value of
CONSUMING INDEX AttributeConsumingServiceIndex of SAML 2 authentication
requests. If SAML2 ATTRIBUTE CONSUMING INDEX is not configured
in SAML 2.0 options, then Access Manager considers the SAML2
ATTRIBUTE CONSUMING INDEX configuration in Identity Server
global options. If you require to assign the property values for
multiple entries, you can use comma (,) as separator.

You can provide the value in the format specified in the following
example:

For protected resource URL: https://www.example.com:446/

test/Test/test.php->2

In this example, the value 2 is assigned to

AttributeConsumingServiceIndex of SAML 2 authentication
request coming from the mentioned protected resource.

For default value: default->10

If the SAML 2 authentication request comes from the protected

resource that is not configured, then the default value, 10 gets
assigned to AttributeConsumingServiceIndex.

For multiple protected resource URLs: https://

www.example.com:446/test/Test/test.php->2,https://
www.example.com:446/test/Test/view.php->3

SECURE CLUSTER COOKIE Select false to disable the secure flags for cluster cookies. The default
value is true.

For example, see Section 32.3.11, “Enabling Secure or HTTPOnly Flags

for Cluster Cookies,” on page 1319.

STS CHANGE ISSUER Specify the value in this format: SPentityID:UPNDomain ->
new IssuerID. For example,
urn:federation:MicrosoftOnline:support.namnetiq.in -> https://
namnetiq.in/nidp/wsfed/

In case of multiple children domains, add each parent domain and

child domain separated by a comma. For example, if namnetiq.in is
the parent domain and support.namnetiq.in and
engineering.namnetiq.in are children domains, specify the following
entries:

urn:federation:MicrosoftOnline:namnetiq.in ->
https://namnetiq.in/nidp/wsfed/,
urn:federation:MicrosoftOnline:support.namnetiq.i
n -> https://namnetiq.in/nidp/wsfed/,
urn:federation:MicrosoftOnline:engineering.namnet
iq.in -> https://namnetiq.com/nidp/wsfed/

For example, see “Configuring Federation for Multiple Domains” on

page 682.

Setting Up a Basic Access Manager Configuration 59

 Property Value

STS OFFICE365 MULTI Select true to enable users to access Office 365 services by using the
DOMAIN SUPPORT AUTO Issuer URI specific to the domain they belong to. The default value is
false.

For example, see Creating Multiple Domains in Office 365 and

Establishing Federation with Access Manager.

WSF SERVICES LIST Select full to enable users to access the Services page.

Select 404 to return an HTTP 404 status code: Not Found.

Select 403 to return an HTTP 403 status code: Forbidden.

Select empty to return an empty services list.

The default value is full.

For example, see Blocking Access to the WSDL Services Page.

WSFED ASSERTION VALIDITY Specify the assertion validity time in second for WS Federation
Provider (SP) to accommodate clock skew between the service
provider and SAML identity provider.

The default value is 1800 seconds.

For example, see “Assertion Validity Window” on page 599.

WSTRUST AUTHORIZATION Specify the user names who can perform ActAs operations. Allowed
ALLOWED ACTAS VALUES user names are the user accounts that the intermediate web service
provider uses to authenticate with STS when sending a request with
ActAs elements.

You can specify more than one user name separated by a comma.

For example, see “Adding Policy for ActAs and OnBehalfOf” on

page 615.

WSTRUST AUTHORIZATION Specify the user names who can perform OnBehalfOf operations.
ALLOWED ONBEHALF Allowed user names are the user accounts that the intermediate web
VALUES service provider uses to authenticate with STS when sending a
request with OnBehalfOf elements.

You can specify more than one user name separated by a comma.

For example, see “Adding Policy for ActAs and OnBehalfOf” on

page 615.

WSTRUST AUTHORIZATION Specify the user names who can perform both ActAs and OnBehalfOf
ALLOWED VALUES operations.

You can specify more than one user name separated by a comma.

For example, see “Adding Policy for ActAs and OnBehalfOf” on

page 615.

60 Setting Up a Basic Access Manager Configuration

Property Value

SESSION ASSURANCE USER Specify the user-agent string for that you want to disable the session
AGENT EXCLUDE LIST validation.

For example, see “Disabling Advanced Session Assurance for Identity

Server” on page 1029.

SESSION ASSURANCE USER Specify the user-agent REGEX for that you want to disable the session
AGENT REGEX EXCLUDE LIST validation.

For example, see “Disabling Advanced Session Assurance for Identity

Server” on page 1029.

SESSION ASSURANCE URL Specify the URL for that you want to disable the session validation.
EXCLUDE LIST
For example, see “Disabling Advanced Session Assurance for Identity
Server” on page 1029.

SESSION ASSURANCE URL Specify the URL REGEX for that you want to disable the session
REGEX EXCLUDE LIST validation.

For example, see “Disabling Advanced Session Assurance for Identity

Server” on page 1029.

SESSION ASSURANCE IDC Specify the time in second till which Identity Server will accept the
COOKIE GRACEPERIOD old IDC cookie after issuing a new cookie. The default value is 15
second.

OTHER Specify Property Name and Property Value if you want to configure
any other property.

NAM_DFP_KEYS_ENFORCE_S Click OTHER to configure this property.

TRICT
When Advanced Session Assurance is enabled, specify true to send
session keys only the first time when the device information is
fetched. Specify false to send session keys every time whenever
device information is fetched. The default value is false.

ENCODE_TARGET_URL_QUE Click OTHER to configure this property.

RY
When this option is set to true, the target URL query (SAML Request)
is URL encoded. This option is set to true by default.

When you set this option to false, the following will happen after
authentication:
 The target URL query is not URL encoded
 The user is not redirected to the service provider
 The following message is displayed:

<amLogEntry> 2018-08-20T17:00:18Z WARNING NIDS

Application: Error during Inflate.
Exception message: "It should be divisible by
four"

Setting Up a Basic Access Manager Configuration 61

 Property Value

NMAS_SAML_SIGN_METHO Click OTHER to configure this property.

DDIGEST_SHA256
Set this option to true while using the NMAS SAML method. When
(This option is available in you set this option to true, it uses SHA265 algorithm for SAML 2
Access Manager 4.5 Service assertion. If this property is not configured or the value is set to false,
Pack 1 or later versions) SHA1 algorithm is used.

This option is set to false by default.

persist_caches_on_reconfigu Click OTHER to configure this property.

re
After you update a configuration or reconfigure it, the user session
(This option is available in details and read attributes get deleted from the cache. Set this option
Access Manager 4.5 Service to true to retain the details after a configuration update.
Pack 3 or later versions)

OAUTH_CLAIMS_TO_USE_LD Click OTHER to configure this property.

AP_ATTR_FORMAT
Set this option to true to configure the OAuth claims data type
(This option is available in according to the LDAP attribute's schema data type. If the LDAP
Access Manager 4.5 Service attribute data type is single-valued, the claims data is returned as a
Pack 3 Hotfix 1 or later string. If the LDAP attribute data type is multi-valued, the claims data
versions) is returned as a string array irrespective of the value count.

For example, let us assume that a client application uses the

Authorization Code flow and sends the access token to the
userinfo endpoint. Then you can choose the format of the token's
attribute data type that will be returned.

The following is an example of attributes when this property is not

configured or set to false:

"family_name": "Lastname"

The following is an example of attributes when this property is set to

true:

"family_name": [
"Lastname"
]

This option is set to false by default.

4 Click OK > Apply.

2.3 Configuring Identity Server Shared Settings

You can use shared settings in any Identity Server cluster configuration.
You can define the following shared settings:
 Attribute sets: See Configuring Attribute Sets and Editing Attribute Sets.
 Custom Attributes: See Adding Custom Attributes.

62 Setting Up a Basic Access Manager Configuration

  Data Sources: See User Attribute Retrieval and Transformation.
 Virtual Attributes: See User Attribute Retrieval and Transformation.
 Authentication card images: See Adding Authentication Card Images and Creating an Image
Set.
 Metadata Repositories: See Metadata Repositories.
 User matching expressions: See Configuring User Matching Expressions.

The Shared Settings page also contains tabs for configuring the server details for NetIQ Advanced
Authentication and Self Service Password Reset products. You need to configure these details when
integrating Access Manager with these products.
 Configuring Advanced Authentication Server
 Configuring Self Service Password Reset Server Details in Identity Server

2.3.1 Configuring Attribute Sets

The attributes you specify on Identity Server are used in attribute requests and responses,
depending on whether you are configuring a service provider (request) or identity provider
(response). Attribute sets provide a common naming scheme for the exchange.
For example, an attribute set can map an LDAP attribute, such as givenName to the equivalent
remote name used at the service provider, which might be firstName. You can use these shared
attributes for policy enforcement, user identification, and data injection.
Example 1: Attribute sets provide the centrally configurable means to map identity attributes
between federation partners. When Access Manager Identity Server provides authenticated user
information to a federated service provider such as Office 365, the attribute set determines what
identity information is sent and available to Office 365 during and after authentication. The source
of the identity data being sent can be the user's local LDAP directory or can be calculated
dynamically. The identity data from external databases and secondary LDAP directories is achieved
through virtual attributes. Virtual attributes are dynamically calculated attributes populated by the
Attribute Retrieval and Transformation feature. See Section 2.3.4, “User Attribute Retrieval and
Transformation,” on page 68.
Example 2: You could have a web server application that requires a user’s e-mail address. You
configure the web server to be a protected resource of Access Gateway, and you configure an
Identity Injection policy to add the user’s email address to a custom HTTP header. When the user
accesses the protected resource, the value of the email attribute is retrieved. However, if you create
an attribute set with this attribute and assign it to be sent with the authentication response of
Access Gateway ESP, the value is cached at authentication and is immediately available. If you have
multiple attributes that you are using in policies, obtaining the values in one LDAP request at
authentication time can reduce the amount of LDAP traffic to your user store.
You can define multiple attribute sets and assign them to different trusted relationships. You can also
use the same attribute set for multiple trusted relationships.
Perform the following steps to create and configure an attribute set:
1 Click Devices > Identity Server > Shared Settings > Attribute Sets > New.
2 Specify the following details:

Setting Up a Basic Access Manager Configuration 63

 Field Description

Set Name Specify a name for identifying the attribute set.

Supports WSTrust and Select this option if you require to add the LDAP attributes and the virtual
OAuth attributes to an attribute set.

For the OAuth scope, you can add LDAP attributes or only the virtual
attributes that are LDAP attributes or are constants.

Select set to use as Select an existing attribute set that you have created, which you can use as a
template template for the new set, or select None. To modify an existing attribute set,
select that set as a template.

3 Click Next.
4 To add an attribute to the set, click New.
5 Specify the following details:

Field Description

Local Attribute Select an attribute from the list of all server profile, LDAP, shared secret attributes
and virtual attributes.

For example, you can select All Roles to use in role policies, which enables trusted
providers to send role information in authentication assertions. Share secret
attributes must be created before they can be added to an attribute set. For
instructions, see “Creating Shared Secret Names” on page 66.

Constant Specify a value that is constant for all users of this attribute set. The name of the
attribute that is associated with this value is specified in Remote Attribute.

Remote Attribute Specify the name of the attribute defined at the external provider. The text for
this field is case-sensitive.
 A value is optional if you are mapping a local attribute. If you leave this field
blank, the system sends an internal value that is recognized between
Identity Servers.
For a SAML 1.1 and SAML 2.0 identity consumer (service provider), a name
identifier received in an assertion is automatically given a remote attribute
name of saml:NameIdentifier. This allows the name identifier to be mapped
to a profile attribute that can then be used in policy definitions.
 A value is required if you are mapping a constant.
An attribute set with a constant is usually set up when Identity Server is
acting as an identity provider for a SAML or Liberty service provider. The
name must match the attribute name that the service provider is using.

64 Setting Up a Basic Access Manager Configuration

 Field Description

Remote Specify the namespace defined for the attribute by the remote system:
namespace  If you are defining an attribute set for LDAP, select none. If you want a
service provider to accept any namespace specified by an identity provider,
select none. If you want an identity provider to use a default namespace,
select none. The urn:oasis:names:tc:SAML:1.0:assertion value
is sent as the default.
 If you are defining an attribute set for WS Federation, select the radio button
and specify the following name:

http://schemas.xmlsoap.org/claims

 If you want to specify a new namespace, select the radio buttonand specify
the name.

Remote format Select one of the following formats:

 unspecified: Indicates that the interpretation of the content is
implementation-specific.
 uri: Indicates that the interpretation of the content is application-specific.
 basic: Indicates that the content conforms to the xs:Name format as defined
for attribute profiles.

Attribute value Select one of the following encoding options:

encoding  Special characters encoded: Encodes only the special characters in the
attribute value.
 Not encoded: Does not encode the attribute value.
 Entire value encoded: Encodes the entire attribute value.

6 Click OK.
7 Click Finish.
The system displays the map on the Attribute Sets page and indicates whether it is in use by a
provider.
8 (Conditional) To configure a provider to use the attribute set, see Section 2.7.6, “Selecting
Attributes for a Trusted Provider,” on page 198.

2.3.2 Editing Attribute Sets

1 Click Devices > Identity Server > Shared Settings > Attribute Sets.
2 Click the name of the attribute set that you want to edit.
3 The system displays an attribute set page with the following tabs:
General: Click to edit the name of the attribute set.
Mapping: Click to edit the attribute map.

Setting Up a Basic Access Manager Configuration 65

 NOTE: After editing the attribute mapping, verify the attribute set again in the trusted
provider's list. Select the attributes from the Available list, and move them to the left side of the
page. Update Identity Server.

Usage: Displays where the attribute set is used. Informational only.

4 Click OK > Close.

2.3.3 Adding Custom Attributes

You can add custom shared secret names or LDAP attribute names that you want to make available
for selection when setting up policies.
 Section 2.3.3.1, “Creating Shared Secret Names,” on page 66
 Section 2.3.3.2, “Creating LDAP Attribute Names,” on page 67

2.3.3.1 Creating Shared Secret Names

The shared secret consists of a secret name and one or more secret entry names. You can create only
a secret name, or a secret name and an entry name. For ease of use, the entry name must match the
policy that uses it:
 For a Form Fill policy, the entry name must match a form field name.
 For an Identity Injection policy, the entry name must match the Custom Header Name.
 For an External Attributes policy, Secret Name must match the policy name and Secret Entry
Name must match the attribute name configured while creating the policy.
For example, if the policy name is fetchattr and attribute name configured in the policy is
address, then Secret Name must be fetchattr and Secret Entry Name must be address.

For more information about how to use shared secrets with policies, see Section 10.5.4, “Creating
and Managing Shared Secrets,” on page 938.
Identity Server needs to be configured to use shared secrets. For information about this process, see
“Configuring a User Store for Secrets” on page 389.
Shared secret names can be created on the Custom Attributes page or in the associated policy that
consumes them.
1 Click Devices > Identity Servers > Shared Settings > Custom Attributes > New.
2 Specify a new shared secret name and, optionally, a secret entry name.
3 Click OK.
4 (Optional) To create additional entries for the secret, click the name of the secret, click New,
specify an entry name, and click OK.

WARNING: Identity Server cannot determine whether a secret is being used by a policy. Before you
delete a shared secret, you must ensure that it is not being used.

66 Setting Up a Basic Access Manager Configuration

2.3.3.2 Creating LDAP Attribute Names
LDAP attributes are available for all policies. LDAP attribute names can be created on the Custom
Attributes page or in the associated policy that consumes them. The attribute names that you
specify must match the name of an attribute of the user class in your LDAP user store.
1 Click Devices > Identity Servers > Shared Settings > Custom Attributes.
This list contains the attributes for the inetOrgPerson class. It is customizable.
 audio: Uses a u-law encoded sound file that is stored in the directory.
 businessCategory: Describes the kind of business performed by an organization.
 carLicense: Vehicle license or registration plate.
 cn: The X.500 commonName attribute, which contains a name of an object. If the object
corresponds to a person, it is typically the person’s full name.
 departmentNumber: Identifies a department within an organization.
 displayName: The preferred name of a person to be used when displaying entries. When
displaying an entry, especially within a one-line summary list, it is useful to use this value.
Because other attribute types such as cn are multivalued, an additional attribute type is
needed.
 employeeNumber: Numerically identifies a person within an organization.
 employeeType: Identifies the type of employee.
 givenName: Identifies the person’s name that is not his or her surname or middle name.
 homePhone: Identifies a person by home phone.
 homePostalAddress: Identifies a person by home address.
 initials: Identifies a person by his or her initials. This attribute contains the initials of an
individual, but not the surname.
 jpegPhoto: Stores one or more images of a person, in JPEG format.
 labeledURI: Uniform Resource Identifier with an optional label. The label describes the
resource to which the URI points.
 mail: A user’s e-mail address.
 manager: Identifies a person as a manager.
 mobile: Specifies a mobile telephone number associated with a person.
 o: The name of an organization.
 pager: The pager telephone number for an object.
 photo: Specifies a photograph for an object.
 preferredLanguage: Indicates an individual’s preferred written or spoken language.
 roomNumber: The room number of an object.
 secretary: Specifies the secretary of a person.
 sn: The X.500 surname attribute, which contains the family name of a person.
 uid: User ID.
 userCertificate: An attribute stored and requested in the binary form.

Setting Up a Basic Access Manager Configuration 67

  userPKCS12: A format to exchange personal identity information. Use this attribute when
information is stored in a directory service.
 userSMIMECertificate: PKCS#7 SignedData used to support S/MIME. This value indicates
that the content that is signed is ignored by consumers of userSMIMECertificate values.
 x500uniqueIdentifier: Distinguishes between objects when a distinguished name has been
reused. This is a different attribute type from both the uid and the uniqueIdentifier type.
2 Add a name:
2a Click New.
2b If you want the attribute to return raw data instead of binary data, select 64-bit Encode
Attribute Data.
2c Click OK.
3 To modify the 64-bit attribute data encoding, select an attribute, and click one of the following
options:
 Set Encode: Specifies that LDAP returns a raw format of the attribute rather than binary
format. Access Manager encodes to base64, so that the protected resource understands
the attribute. Use the base64 encoding if certificates require raw bites rather than the
binary string format.
 Clear Encode: Deletes the 64-bit data encoding setting.
4 Click Apply.
5 Click the Servers tab to return to the Servers page.

2.3.4 User Attribute Retrieval and Transformation

The User Attribute Retrieval and Transformation feature enables you to retrieve an attribute from an
external data source and transform it before sending it in an assertion. The data source can be any
database, REST web service, or LDAP repositories. This feature also allows you to transform user’s
local attributes, LDAP attributes, Shared Secrets, and various profiles, such as Personal Profile and
Employee Profile.
Virtual attributes can be used to generate dynamic data at runtime from the current values of the
user attributes.
The transformed attribute values are not stored in any persistent data stores. They are in the
memory as part of user’s session.
 Section 2.3.4.1, “How User Attribute Retrieval and Transformation Helps,” on page 69
 Section 2.3.4.2, “Prerequisites,” on page 69
 Section 2.3.4.3, “Managing a Data Source,” on page 69
 Section 2.3.4.4, “Managing an Attribute Source,” on page 74
 Section 2.3.4.7, “Managing a Virtual Attribute,” on page 81
 Section 2.3.4.8, “Retrieving Attributes from a REST Web Service,” on page 85
 Section 2.3.4.9, “Sample JavaScripts with Examples,” on page 92
 Section 2.3.4.10, “Troubleshooting User Attribute Retrieval and Transformation,” on page 99
 Section 2.3.4.11, “User Attribute Retrieval and Transformation Limitations,” on page 99

68 Setting Up a Basic Access Manager Configuration

2.3.4.1 How User Attribute Retrieval and Transformation Helps
User Attribute Retrieval and Transformation helps you to perform the following activities:
 Retrieve attribute values from external sources other than the configured user stores. The
sources can be an external REST web service, an external database, or any external LDAP
repository.
 Transform attribute values before they are sent as part of an assertion to a federated provider.
For example, you can edit an attribute value before it is sent from identity provider to a service
provider in a SAML 2.0 federation. You can also edit an attribute value sent from identity
provider to Access Gateway used in policies.
 Transform the attribute value used in policies. For example, you can transform Identity Server
role-based policies.
User Attribute Retrieval and Transformation introduces the following configuration settings in
Identity Server:
 Data Source: An entity that holds configuration properties that help in connecting to an
external data source. The properties of the data source can be defined in the data source user
interface. A data source can be a REST web service, an LDAP repository, or an SQL database.
 Attribute Source: Represents queries that fetch attributes from a data source. You can define an
LDAP search filter or an SQL query. You can also define requests and configure the response to
retrieve attributes from a REST web service resource endpoint.
 Virtual Attribute: Helps you specify the attributes that must be transformed and in the way the
transformations happen. A virtual attribute can transform multi-valued attributes.

2.3.4.2 Prerequisites
To perform complex user attribute transformations, you must have a basic understanding of
JavaScript. To see sample JavaScripts with examples, see “Sample JavaScripts with Examples” on
page 92.

2.3.4.3 Managing a Data Source

You can create, edit, or delete a data source.

NOTE: You cannot delete a data source that is being used by an attribute source.

This section discusses the following topics:

 “Creating a Data Source” on page 69
 “Editing a Data Source” on page 74

Creating a Data Source

To create a data source, perform the following steps:
1 Click Devices > Identity Server > Shared Settings > Data Sources.
2 Click + to add a data source.

Setting Up a Basic Access Manager Configuration 69

 3 Select one of the following data sources:
 Rest Web Service: Continue with Step 4 on page 70.
The data source of REST web service contains only the common information that is
required by the endpoints, such as base URL, setting trusted root, and authentication. If
you require to retrieve attributes by using REST API calls from an external REST web
service, you must add the REST web service data source.
 Database: Continue with Step 5 on page 71.
Supported databases include Oracle and Microsoft SQL.
 LDAP: Continue with Step 6 on page 72.
eDirectory and Active Directory are supported. You can create multiple search context and
LDAP replicas.
4 (For Database) Specify the following details:

Field Description

Database Name Specify the name of the database.

Database Driver Select a driver from the list. The associated driver name is auto-populated. If
you select Others (Unsupported), specify the driver name in the adjacent
field.

Max Connections Specify the maximum number of connections. The default value 20.

Idle TimeOut Specify the idle timeout. The default value is 600000 milliseconds. Set this
value based on the server setting. For example, if the server timeout value is
600000, then the timeout value must not exceed 600000.

Connection TimeOut Specify the connection timeout. The default value is 10000 milliseconds. Set
this value based on the server setting.

Username Specify the username used to read from the database.

Password Specify the password used to read from the database.

Confirm Password Specify the password again.

URL Specify the database URL based on the database driver selected.

Based on the database type, you need to add the corresponding jars.
For Oracle:
1. Download the JDBC connector for the Oracle database from Oracle.com (https://
www.oracle.com/technetwork/database/enterprise-edition/downloads/index-
092322.html).
2. Copy the JDBC connector jar to the following folder:
On Windows
 Administration Console: C:\Program
Files\Novell\Tomcat\webapps\nps\WEB-INF\lib
 Identity Server: C:\Program Files\Novell\Tomcat\webapps\nidp\WEB-
INF\lib

70 Setting Up a Basic Access Manager Configuration

 On Linux
 Administration Console: /opt/novell/nam/adminconsole/webapps/nps/WEB-
INF/lib
 Identity Server: /opt/novell/nam/idp/webapps/nidp/WEB-INF/lib
3. Restart Administration Console and Identity Server.
For Microsoft SQL Server:
1. Download the JDBC connector for the SQL Server database from Microsoft (https://
www.microsoft.com/en-in/download/details.aspx?id=11774).
2. Copy the JDBC connector jar file to the following folder:
On Windows
 Administration Console: C:\Program
Files\Novell\Tomcat\webapps\nps\WEB-INF\lib
 Identity Server: C:\Program Files\Novell\Tomcat\webapps\nidp\WEB-
INF\lib
On Linux
 Administration Console: /opt/novell/nam/adminconsole/webapps/nps/WEB-
INF/lib
 Identity Provider: /opt/novell/nam/idp/webapps/nidp/WEB-INF/lib
3. Restart Administration Console and Identity Server.
5 (For LDAP) Specify the following details:
5a Specify LDAP Properties:

Field Description

LDAP Name Specify a display name for the LDAP database.

Directory Type Select the type of directory. If you select Others (Unsupported),
specify a directory name in the adjacent field: sunonedir, custom1,
custom2, custom3, custom4, others.

Username Specify the username used to read from the database.

Password Specify the password used to read from the database.

Confirm Password Specify the password again.

LDAP Operation TimeOut Specify the LDAP operation timeout. The default value is 15000
milliseconds. You can set this value based on the server setting.

Idle Connection TimeOut Specify the connection timeout. The default value is 10000
milliseconds. Set this value based on the server setting. For
example, if the server timeout is 15000 milliseconds, then the LDAP
timeout value must not exceed 15000.

5b Specify required number of contexts under Search Contexts.

5b1 Click Actions > Add Search Context.
5b2 Specify Search context to locate users in the directory.
5b3 Select the scope such as One level, Object, or Subtree in Scope.

Setting Up a Basic Access Manager Configuration 71

 If a user exists outside of the specified search context and its scope (One level, Object
or Subtree), Identity Server cannot find the user and the search fails.
5b4 Click Save.
5c Specify required number of LDAP replicas under LDAP Replicas.
5c1 Click Actions > Add LDAP Replica.
5c2 Specify the following details to add a LDAP replica:

Field Description

Name Specify a name to represent the LDAP replica.

IP Address Specify the IP address of the LDAP directory.

Port Specify the port number. By default, it is 389.

For a secure connection, select Use Secure LDAP Connection. The port
number changes to 636.

You must import the trusted root if you select a secure connection. To
import the trusted root, click Auto Import Trusted Root. The trusted
certificate of the server will be imported to the Identity provider trust
store. Update the Identity provider each time.

Max Connections Specify the maximum number of connections. By default, it is set to

20.

5c3 Click Save.

6 (For REST Web Services) Specify the following details:

Field Description

Web Service Name Specify a display name for the web service.

This can be any alpha-numeric name.

Description (Optional) Specify the description for the web service.

Base URL Specify the base URL in the <protocol>://<host>:<port> format. For
example: http://172.16.0.0:80

Here, protocol can be HTTP or HTTPS.

This is a common URL that can be used for the endpoints that use the same
host and port. A common URL is used because the authentication and data
connection properties will be common for all endpoints.

For example, you can use the base URL as www.abc.com/rest if you want to
retrieve user attributes from the following REST endpoints:
 www.abc.com/rest/getUserDepartmentInfo
 www.abc.com/rest/getUserInfo

You can add getUserDepartmentInfo and getUserInfo in Resource/API Path in

the attribute source page. The attribute source page is used for retrieving
attributes that are specific to each web service endpoint.

72 Setting Up a Basic Access Manager Configuration

 Field Description

Trusted Root Select one of the following options:

 Verify from IDP trust store: Select this option if Identity Server must
verify the SSL certificate of the web service.
To import the trusted root from a specific web service, click Manage Web
Service Trust Store.
The trusted certificate of the server will be imported to the Identity Server
trust store. Update the Identity Server each time.
 Do not verify: Select this option if you do not require Identity Server to
verify the SSL certificate of the web server.

Connection Specify the duration until which Access Manager must try connecting to the
Timeout REST web server in milliseconds. The default value is 15000 milliseconds. If the
host is not reachable, clicking Test will give the timeout error after the specified
duration.

Authentication Select the type of authentication that will be required for connecting to the
Type required web service.

If you select Basic Auth, the Authorization header with the specified username
and password gets added automatically to the request header, which is used for
retrieving data from a REST endpoint.

This ensures that the Authorization header gets added under the request
header in the attribute source page.

Credentials This field is displayed only when you select Authentication Type as Basic Auth.

You can select any one of the following options:

Admin: Specify the username and password for accessing the REST endpoints.
Select this option if the REST web server requires a common credential to
access all endpoints.

Custom: Specify required LDAP attribute of users for accessing the REST
endpoints. Use this option if the access to REST web server endpoints require
specific user credentials.

You must specify the credentials that authorizes a user to retrieve the
information from the REST web server.

7 To test the data source connection after specifying the details, click Test under Test Connectivity.
You can also view the error logs at the following location:
Linux: /opt/novell/nam/logs/adminconsole/tomcat/catalina.out
Windows: c:\Program Files\Novell\Tomcat\logs\stdout.log

NOTE: For a REST web service, clicking Test checks the connection to the web service
irrespective of the endpoint's resource path and credentials. It checks the connection based on
the IP address and port.

Setting Up a Basic Access Manager Configuration 73

 Editing a Data Source
1 Click Devices > Identity Server > Shared Settings > Data Sources.
2 Click the data source you want to modify.
3 On the Edit Data Source page, modify the details as required.

NOTE: If you change the IP address of the LDAP or REST web service data source, then, you
must import the trusted root of the updated server to the Identity Server trust store.

For more information about the fields on this page, see “Creating a Data Source” on page 69.
4 Click OK.
5 Update Identity Server.

IMPORTANT: You must update Identity Server every time you edit the properties of a data source
that is being used by an attribute source and the attribute source in turn, being used by the virtual
attribute.

2.3.4.4 Managing an Attribute Source

You can create, edit, or delete an attribute source.

NOTE: You cannot delete an attribute source that is being used by a virtual attribute.

This section discusses the following topics:

 “Creating an Attribute Source” on page 74
 “Editing an Attribute Source” on page 81

Creating an Attribute Source

1 Click Devices > Identity Server > Shared Settings > Virtual Attributes > Attribute Source.
2 Click + to add an attribute source.
3 Specify a name and description for the attribute source.
4 Select the data source.
5 Specify the following details in Step 1: Provide input parameters:

Field Description

Name The default value is %P1% or {P1} based on the selection of data source.

Specify the same name in Query or in fields that use the value of the attribute.

Parameter Value Select an attribute from the list.

74 Setting Up a Basic Access Manager Configuration

 Field Description

Show / Add Test Click this to display the test value, and specify a value in Test value.
Values?
This value is used later when testing the query string or the web service.

For REST web service, the input parameters can be used in creating resource API
path, request headers, request body and the Advanced: Javascript response
parsing functions. These can be tested using the test values. To use the input
parameters, you must provide the parameter in the {<parameter name>}
format, such as {P1}.

When you click Test, the Test Results pane displays the status of the request and
response based on the specified values.

NOTE: For LDAP and database, the attribute source does not support multi-valued inputs. If you
input multiple values, only one value is picked for the calculation.
For REST web service, the attribute source supports multi-valued inputs for a parameter.

6 (Conditional) For LDAP or database, specify the following details in Step 2: Provide query and
output parameters:

Field Description

Query Specify an LDAP filter or a database query.

The query must use the value specified in Step 1: Provide input parameters.

Query Output Specify a name for the query output.

Parameters
To add multiple output parameters, click Add.
 For an LDAP filter, specify the exact name of the attribute that you want to
fetch.
 For a database query, specify an alias for the attribute fetched. The order of
the output parameters must match the sequence in which they are specified in
the database query.

Test Click to test the input values based on the filter and output parameters.

For security reasons, you are prompted to enter the data source credentials. Test
Result displays the status along with the test results. You can also view the error
logs at the following location:

Linux: /opt/novell/nam/logs/adminconsole/tomcat/catalina.out

Windows: \Program Files\Novell\Tomcat\logs\stdout.log

Example 2-5 Sample configuration

See “A Sample LDAP Scenario” on page 79 and “A Sample Database Scenario” on page 79.
7 (Conditional) For REST web service, specify the following details in Step 2: Configure Request
and Response:

Setting Up a Basic Access Manager Configuration 75

 Field Description

Base URL Auto-populated based on the details specified for the data source.

Resource/API Specify the path of resource or API to be used along with the base URL to send a
Path request to the REST web service.

For example, if you require to fetch attributes from the www.abc.com/rest/

getUserInfo endpoint and the base URL is www.abc.com/rest/, then
specify Resource/API Path as getUserInfo.

If REST web service requires the input parameters defined in Step 1: Provide input
parameters, select Plain Text or Javascript and use the parameter within
Resource/ API Path.

Plain Text Select this when you need to add simple values, such as a constant value and
unmodified input parameter values. You can use Plain Text in the following
scenarios:
 If the REST web server requires a constant value, such as user1, to be
available in the resource/ API path, select Plain Text and specify Resource/
API Path as /getuserinfo/user1.
 If the REST web server requires a user name to be available in Resource/ API
Path for different users, use the input parameter {P1} with the givenName
value to specify Resource/ API Path, such as /getuserinfo/{P1}.

Javascript Select this when you need to add and modify complex values in Resource/ API
Path. For example, if in the endpoint URL, REST web server requires the user’s
name in lower case along with the last name in lowercase, you can specify the
following in Resource/ API Path:

function main({P1},{P2})
var ret='/getuserinfo/'+ {P1}.toLowerCase()+"/
"+{P2}.toLowerCase();
return ret;
}

The return type of JavaScript can be string or array.

NOTE: The input parameter can include multiple values, such as email (it can have
values [email protected] and [email protected]). The multi-valued input
parameter in the JavaScript main function are sent as a JavaScript array. If this
attribute contains a single value for a specific user, this attribute is sent as a string
to the JavaScript main function. So, ensure to check whether a parameter is sent
as a string (single value) or as an array (multiple values) before processing it in the
JavaScript main function.

Method Select the request method that is accepted by the REST web server.

GET and POST are the supported methods.

76 Setting Up a Basic Access Manager Configuration

Field Description

Request Headers Add request headers based on the REST endpoint configuration. By default, the
and Body Authorization header gets generated if you have selected Basic Auth during the
creation of the REST web service Data source.

You can add multiple headers for specific endpoints when configuring request
headers. You can use the input parameter in the header value such as, {P1}.

Specify the body message in plain text or JSON format. To specify the message
using JavaScript, select Javascript.

When you write a script, ensure that you request for the values that are either in
string or in JSON format.

Plain Text Select to include a constant input value or any input parameter value in the
request body.The following example helps in understanding how to use the values
in request body using plain text format:
 If the body request should contain the constant values such as, john123
(userid), and abc (department) then you can specify Request Body as
{"userid": "john123", "department" : "abc"}
 If the body request should contain some specific value that is variable and is
not modified, then you can specify Request Body as { "userid":
{P1}, "department" : {P2}}

Javascript Select to include a complex request body that requires modified input parameter
values.The following example helps in understanding how to use the values in
request body using JavaScript format:

function main({P1}, {P2}){

var ret = '{ "userid":"'+ {P1} + '","department" : "'+
{P2}+'"}';
return ret;
}

Response To extract a specific response portion from the REST web server response, select
Parsing Function the required response parsing function from the list.
and Parameters
When a response is returned, you can use response parsing function to retrieve
specific parameters that get mapped to the response parameters. This helps in
retrieving the required values from the response. The Advanced: Javascript
response parsing function can return single value (string, number, JSON) or multi-
valued (array of strings, array of JSON) that get mapped to response parameters.

Choose the required response parsing function along with its inputs under
Response Parsing Function and Parameters. If you do not require to use the
functions, you can choose No Response Parsing Function.

For more information about each function, see “Response Parsing Functions” on
page 86.

Setting Up a Basic Access Manager Configuration 77

 Field Description

Add Click to add parameter names to map to the values retrieved from the analyzed
response.

Response_As_Is is the default parameter that includes the complete response as

it is received from the web server. You cannot delete Response_As_Is.
 Sample JSON Response:

{
attribute1: "abc"
attribute2: "pqr"
}

You get Response_As_Is under Response Parameters and you can specify
attribute1 and attribute2 under Response Parameters. This maps
the Response Parameters to the attribute values in the JSON response.
Hence, attribute1 is mapped to abc and attribute2 is mapped to
pqr.
 Sample Array Response:

result[0]
result[1]

You get Response_As_Is under Response Parameters and you can specify
param1 and param2 under Response Parameters. This maps the Response
Parameters to the attribute values in the array response. Hence, param1 is
mapped to result[0] and param2 is mapped to result[1].
For more information about mapping the parameters with the required
attribute, see “Retrieving Attributes from a REST Web Service” on page 85.

Example 2-6 Sample configuration

See “A Sample REST Service Scenario” on page 79.

8 To test this configuration:
1. In Step 1: Provide input parameters, select Show / Add Test Values?, and provide a test value
that is available as an attribute in the REST web server endpoint.
2. In Step 2: Configure Request and Response, click Test. Specify the credentials that is defined
while creating the data source. (See “Creating a Data Source” on page 69)
Test results display the status for request and response. You can view the request URL,
Headers, and Body under Request and view response parameters and headers under
Response. The value of the parameters as retrieved from the response parsing function
gets displayed in the test result window.
The test result window displays the error message when the test result fails. For more
information about the error you can check the logs at the following location:
Linux: /opt/novell/nam/logs/adminconsole/tomcat/catalina.out
Windows: c:\Program Files\Novell\Tomcat\logs\stdout.log

78 Setting Up a Basic Access Manager Configuration

A Sample LDAP Scenario
You want to fetch an email address from an external LDAP directory for which a user’s LDAP attribute
(from the external LDAP directory) UID matches with the local LDAP attribute cn.
To achieve this, perform the following steps:
1. In Step 1: Provide input parameters, select LDAP attribute: cn as a parameter value. Add input
parameter %P1% and map it to the LDAP attribute.
2. In Step 2: Provide filter and output parameters:
a. Specify (&(objectclass=*)(uid=%P1%)).
b. Specify the filter output name as email. email is the alias name given for the column
email.
3. Test this configuration.
a. In Step 1: Provide input parameters, select Show / Add Test Values? and provide the test
value as admin.
b. In Step 2: Provide filter and output parameters: Click Test. Enter the data source credentials.
The test result returns the email address stored in the directory: [email protected].

A Sample Database Scenario

You want to fetch an email address from the database for which a user’s name matches with the
local LDAP attribute cn.
To achieve this, perform the following steps:
1. In Step 1: Provide input parameters, select LDAP attribute: cn as the parameter value.
2. In Step 2: Provide query and output parameters:
a. Specify select email from Emp where name = '%P1%' (email and name are the
column name and Emp is the table name)
b. Specify the filter output name as mail (mail is the alias name given for the column email).
3. Test this configuration.
a. In Step 1: Provide input parameters, select Show / Add Test Values?, and provide a test value
that represents a record in the column of the table.
b. In Step 2: Provide query and output parameters: Click Test. Specify the data source
credentials.
The test results return the email address stored in the database: [email protected].

A Sample REST Service Scenario

You have a web service that returns the roles of a user and you require to retrieve the designation of
the user from the response received.
The endpoint of the REST web service: https://10.10.10.1:8543/rest/catalog/user1/
roles/role

Base URL: https://10.10.10.1:8543/rest/catalog/

Request body:

Setting Up a Basic Access Manager Configuration 79

 "roles": [
{
"id": "cn=user1,cn=system,cn=usrapplication,ou=abc,ou=example,o=com"
}
]
}
Response from REST web server (Response_As_Is):
{
"roles": [
{
"id": "cn=user1,cn=system,cn=usrapplication,ou=abc,ou=example,o=com",
"name": "user1",
"designation": "Provisioning Administrator",
"department": "Engineering",
"level": 20,
"subContainer": "system",
"status": 50
}
]
}
To retrieve the designation of user1 and map to Response Parameter, perform the following steps:
The response parameter mapped to the designation attribute value is used in virtual attribute.
1. In Step1: Provide input parameters, specify {P1} with the givenName value.
This input parameter is required because web server requires the user’s cn information in the
request.
2. In Step 2: Configure Request and Response:
a. Select Plain Text and specify Resource/ API Path as {P1}/roles/role.
Base URL is auto-populated from the value specified in the Data Source page, https://
10.10.10.1:8543/rest/catalog/.
b. Select Method as Post.
In this scenario, the REST web service uses the POST method.
c. In the Headers tab, Authorization is auto-populated. This header is retrieved from the REST
Data Source page.
d. Select Plain Text and specify the request body message:
{
"roles":

{"id":"cn={P1},cn=system,cn=usrapplication,ou=abc,ou=example,o=com"
}
]
}
e. Select JSON Parse with Match Conditions.
f. Specify the following Inputs:
JSON Array Parse String: roles

80 Setting Up a Basic Access Manager Configuration

 Match Conditions:
Name: name
Value: user1
3. Test this configuration.
a. In Step 2: Configure Request and Response, click Test. Specify the data source credentials.
The Response_As_Is parameter is added by default.
b. Click the edit icon next to the Response_As_Is parameter to view the complete response.
To map designation attribute value to an output parameter, you must add
designation as output parameter under Response Parameters.
When the condition (name as user1) finds a match in the response, the designation
value is retrieved and gets mapped to the designation parameter.
For more information about retrieving response parameters, see “Retrieving Attributes from a REST
Web Service” on page 85.

Editing an Attribute Source

1 Click Devices > Identity Server > Shared Settings > Virtual Attributes > Attribute Source.
2 Click the attribute source you want to modify.
3 On the Edit Attribute Source page, modify the details as required.
For more information about the fields on this page, see “Creating an Attribute Source” on
page 74.
4 Click OK. Update Identity Server.

IMPORTANT: If the attribute source is being used by a virtual attribute, you need to update Identity
Server every time you edit the properties of an attribute source.

2.3.4.7 Managing a Virtual Attribute

You can create, edit, or delete a virtual attribute.

NOTE: You cannot delete a virtual attribute that is being used by an attribute set. Before deleting a
virtual attribute, ensure that it is not being used by a policy.

This section discusses the following topics:

 “Creating a Virtual Attribute” on page 81
 “Editing a Virtual Attribute” on page 85

Creating a Virtual Attribute

You can create a virtual attribute from an attribute source and from an external data source.
1 Click Devices > Identity Server > Shared Settings > Virtual Attributes > Virtual Attribute.
2 Click + to create a virtual attribute.
3 Specify a name and description for the virtual attribute.

Setting Up a Basic Access Manager Configuration 81

 4 Click Step 1: Provide input > parameters and specify the following details:

Field Description

Name Specify a name for the attribute. If you use advanced JavaScript option, specify the
same name in Advanced JavaScript. The default value is P1.

Parameter Select an attribute from the list. To specify additional values, click +.
Value
NOTE: If an attribute source returns a null or an empty value, the corresponding
input parameter takes an empty string value.

Show / Add Click to display Test value. You can add, edit, and delete a test value.
Test Values?

5 Click Step 2: Provide a modification function and specify the following details:
 Select a function: Select a function. The corresponding JavaScript is displayed in Script.
Expand the script to view. You can further customize these scripts and use them in
Advanced JavaScript.
The following table lists the pre-defined JavaScript functions with examples:

Function Description Example: Pre-Defined

Functions

To UpperCase Converts the input value to upper case.This If P1=alice, then the
function works on arrays and single-valued input. It result displays ALICE.
uses the toUpperCase() JavaScript function.

Works only on one input parameter that is selected

in Step 1: Provide input parameters

To LowerCase Converts the input value to lower case.This function If P1=ALICE, then the
works on arrays and single-valued input. It uses the result displays alice.
toLowerCase() JavaScript function.

Works only on one input parameter that is selected

in Step 1: Provide input parameters

Remove Removes a substring from all instances of the input If

Substring value. This function does not remove a substring [email protected]
from the global option.This function works on
arrays and single-valued input. It uses the following Remove=@microfocus
JavaScript function: split() and join() , then the result is
a.com.
Works only on one input parameter that is selected
in Step 1: Provide input parameters

Find and Finds and replaces a string from all instances of the If P1=abcde
Replace input value.
Find=e
Works only on one input parameter that is selected
in Step 1: Provide input parameters Replace=a, then the
result displays abcda

82 Setting Up a Basic Access Manager Configuration

Function Description Example: Pre-Defined
Functions

Regex Replace Finds and replaces a substring from all instances of If [email protected]
the input value by using a regular expression.
[email protected]
For example, to search /, you must escape it first
using \. Use the following syntax: /\// Replace=@microfocus.
com
This function works on arrays and single-valued
input. It uses the following JavaScript functions: The result displays:
replace() [email protected]

Works only on one input parameter that is selected

in Step 1: Provide input parameters

Find Subset by Use this function if an input is multi-valued and you If

Regex want a subset of values from it, satisfying a
particular condition by using a regular P1='’[email protected],
expression.This function works on arrays and [email protected],c
single-valued input. It uses the following JavaScript @microfocus.com,
function: replace() [email protected]”

Works only on one input parameter that is selected regex= /microfocus/

in Step 1: Provide input parameters Then, the result
displays:

[email protected],
[email protected]

Concatenate Concatenates multiple values of a multi-valued If P1=abc, def

Values in a input. You must add a separator between the
Parameter values that you want to concatenate Separator=+

Works only on one input parameter that is selected Then, the result
in Step 1: Provide input parameters displays:

abc+ def

Concatenate Concatenates multiple input parameter values, If P1=abc, def

Multiple where each input parameter can be multi-valued
Parameters input. You must add a separator between the and P2=123, 456
values that you want to concatenate Parameter
Separator=+

Multi value
Separator=:

Then, the result

displays
abc:def+123:456

Advanced Specify a customized JavaScript In this field. You See the “Sample
JavaScript need to create a JavaScript function with name JavaScripts with
“main” and specify the code in it. You can write Examples” on page 92.
your custom code or you can also copy the existing
pre-defined code.You can also call multiple
functions in the “main” function.

Setting Up a Basic Access Manager Configuration 83

 Function Description Example: Pre-Defined
Functions

No Modification Use this function if you do not require any

modification to the input parameters.

IMPORTANT: After JavaScript processing, if the output is a null value, the value of the
virtual attribute is empty.
 The pre-defined function can handle both single-valued and multi-valued inputs. If the
input is multi-valued, the pre-defined function is applied on each values.

Advanced JavaScript:
Sample JavaScript:
function main(P1, P2)
{
//some logic
//you can call yourFunction(name) and use its return value
return some value;
}
function yourFunction(name)
{
//some code
//return some value;
}
For advanced JavaScript, the input parameter name in the main function of the JavaScript
must match the input parameter name specified in Step 1: Provide input parameters. The
return value can be a single value or an array.
When the input is multi-valued, it is sent as an array to the main function.
When Identity Server computes the value of a virtual attribute, it calls a function named
main that is available in the script provided for it. The value (single value or array) returned
by main is the value of the virtual attribute.
For example: Consider a scenario where P1 contains bmw and nissan, you can use the
JavaScript instanceof function to check if the input is single-valued or multi-valued. If it
is multi-valued, then JavaScript iterates over the values P1=['bmw', 'nissan']
function main (P1){
if( P1 instanceof Array) {
var a =P1[0] //will assign 'bmw' value to variable a
//do something
}
else{
// if the P1 is single value not a array
//do something
}
}

84 Setting Up a Basic Access Manager Configuration

 The following code checks if an input parameter is empty, contains a value, or undefined:
function main(P1){
if(hasNoValue(P1))
// do something
return something;
}
function hasNoValue(P1){
if(P1 == null || (typeof P1 == 'undefined') || P1.trim().length
== 0)
return true;
else
return false;
}
 Base64 Encode: (Conditional) Select this if you want to encode the modified attribute with
Base64.
 Test: Click this to test the input values based on the modification function. To test multi-
valued inputs, click the + icon.
For example, if an attribute mail has two values: [email protected] and
[email protected], click the + icon twice. In each field, add the values separately.
The test result displays the status with the test results. You can view the error logs at the
following location:
/opt/novell/nam/logs/adminconsole/tomcat/catalina.out
Windows: \Program Files\Novell\Tomcat\logs\stdout.log
6 Click OK.
7 Update Identity Server.

Editing a Virtual Attribute

1 Click Devices > Identity Server > Shared Settings > Virtual Attributes.
2 Click the virtual attribute you want to modify.
3 On the Edit Virtual Attribute page, modify the details as required.
For more information about the fields on this page, see “Creating a Virtual Attribute” on
page 81.
4 Click OK. Update Identity Server.

IMPORTANT: You must update Identity Server every time you edit the properties of a virtual
attribute.

2.3.4.8 Retrieving Attributes from a REST Web Service

This section illustrates examples for the following tasks:
 Sending requests and retrieving responses from a REST web service
 Using Response parsing functions
 Using test values

Setting Up a Basic Access Manager Configuration 85

 Example for Using Input Parameter
You can use the input parameter in the JavaScript format in the request body.
In this example, the endpoint is https://abc.example.com:8543/users/rest/asset/
roles/user. This endpoint uses the POST method for a HTTP request and the following body
content:
{
"users": [
{"id":"cn=
user1,cn=system,cn=userapplication,cn=app1,ou=example,o=com"}
]
}

To change the body content to JavaScript and provide cn from defined input parameters, perform
the following steps:
1 In Step1: Provide input parameters, specify {P1} as input parameter with parameter value cn.
Add the test values for {P1} as user and system.
2 In step 2: Configure Request and Response, change the request body message as follows:

function main({P1}) {
var cnValues = "cn=" + {P1}[0] + ",cn=" + {P1}[1]+
",cn=userapplication,cn=app1,ou=example,o=com";
var json = {
"users": [
{"id":cnValues}
]
};
return json;
}
You can provide multiple test values to a parameter {P1} and use the values as array in the JavaScript
function for Resource/ API Path and Body.

NOTE: If {P1} has only one input value, Access Manager interprets {P1} in JavaScript as a string and
not as an array. Hence, for a single input value use {P1} instead of using {P1}[0].
If multiple values are available for {P1}, JavaScript returns all elements that are separated by a
comma (,). For example, test1,test2. Whereas, {P1} in plain text returns only the first value. For
example, test1.

Response Parsing Functions

When a REST web service receives a request, it returns a response. Access Manager adds the
response body as the Response_As_Is parameter under Response Parameters. This parameter gets
added by default. This function is used to get the specific data from a response. Most of the REST
web services return responses in the JSON format. The response can be sent in any other format,
such as xml and plain text. Access Manager includes the response parsing functions for JSON and
XML. For any response that uses other formats, use the advanced JavaScript option.
You can add test values and click Test to test the result of the request.

86 Setting Up a Basic Access Manager Configuration

The following example explains the response parsing functions:
Sample response returned from REST endpoint (Response_As_Is):
The REST web server returns the data of all students in an array of JSON format as mentioned in the
following sample response:
{
"students": [
{
"name": "xyz",
"id": 1234,
"subjects": [
"English", "French"
],
"department": "dept1",
"branch": "IND"
},
{
"name": "abc",
"id": 124,
"subjects": [
"French"
],
"department": "dept2",
"branch": "IND"
},

{ "name": "pqr",
"id": 223,
"subjects": [
"Spanish"
],
"department": "Dept1",
"branch": "IND"
}]
}
This sample response is used as an example for JSON Parse, JSON Parse with Match Conditions, JSON
Parse with Match Regex, and Advanced: Javascript.

The following is the list of functions:

 JSON Parse: Parse the data with JSON Parse() to retrieve the data from JSON. This modification
function uses the JavaScript’s JSON.Parse function. On selecting this response parsing function,
you must specify JSON Parse String.
Use the following inputs to retrieve specific attributes. You can provide the JSON Parse String
value with standard JavaScript’s JSON.Parse function.

Setting Up a Basic Access Manager Configuration 87

 JSON Parse Scenario Response Test Result
String (input Parameter
value)

students[0].n The value of the name param1 param1=xyz

ame attribute is retrieved
from the first JSON in The output is xyz as the value of the name
the response. This attribute is xyz in the first array of JSON. The
value must be mapped specified Response Parameter is param1, so
to param1. the test result displays it as the parameter in
response.

students[1].n The value of the name name name=abc

ame attribute is retrieved
from the second JSON Here, the output is abc because the value of
in the response. This the name attribute is abc in the second array
value must be mapped of JSON. The specified Response Parameter
to name. is name, so the test result displays it as the
parameter in response.

students[0].su In this scenario, we are param1 param1=English

bjects[0] retrieving the first
value of the Here, the output is English because the
subjects attribute first value of the subjects attribute in the
from the first JSON of first array of JSON is English. The value for
the response. the subjects attribute is in an array
format, so specifying subjects[0] in JSON
Parsing String retrieves the first value in the
array.

students[0].su The second value of param1 param1=French

bjects[1] the subjects
attribute is retrieved The output for param1 is French as it is the
from the first JSON of second value of the subjects attribute in
the response. This the first array of JSON. The value for the
value must map to subjects attribute is in an array format, so
param1. specifying subjects[1] in JSON Parsing
String retrieves the second value in the array.

88 Setting Up a Basic Access Manager Configuration

 JSON Parse Scenario Response Test Result
String (input Parameter
value)

students[0] The values of  name  name=xyz

students is retrieved  id  id=1234
from the first JSON of
the response. These  param1  param1=<no value gets displayed>
values must map with
The output is based on the number of values
name, id and param1
available for the students attribute. In the
in the same order.
first array of JSON, only two values are
available for students. The third parameter
param1 is not mapped to any value.

You can change the order of Response

Parameter by using up and down arrow. The
values are mapped based on the order
specified for Response Parameter. For
example, if the order of Response Parameter
is as follows:
 name
 param1
 id

The output in the Results window displays:

 name=xyz

param1=<no value gets displayed>

 id=1234

 JSON Parse with Match Conditions: This function finds an array from the response and then
apply match conditions on the array elements to find the attribute that matches all the
conditions. The following table includes the sample input value and its result when the data of a
student whose department is dept1 is retrieved:
Scenario: The value of students attribute that includes the attribute name department with
value dept1 is retrieved.

JSON Array Parse Response Test Result

String (input Parameter
value)

students  name  name=xyz

Match Conditions  id  id=1234

 param1  param1=<no value gets displayed>
Name:
When the condition is applied on the students JSON of array,
department
the name parameter matches with name attribute of the response
Value: dept1 and the id parameter matches with the id attribute of the
response. However, no param1 attribute is available in the
response. Therefore, no value gets mapped to param1.

Setting Up a Basic Access Manager Configuration 89

  JSON parse with Match Regex: This is the same as JSON Parse with Match Conditions except
that you can specify regex in the match condition. The following are examples of how to use
regex:
Scenario: Attribute values is retrieved from the students JSON of array that includes the
attribute name as department and the value as dept1. The value dept1 is case-insensitive.

JSON Array Response Test Result

Parse String Parameter
(input value)

students  name  name={

 id "name": "xyz",
Match Regex: "id": 1234,
Name: "subjects": [
"English", "French"
department ],
"department": "dept1",
Regex: /dept1/i "branch": "IND"
}
 id={ "name": "pqr",
"id": 223,
"subjects": [
"Spanish"
],
"department": "Dept1",
"branch": "IND"
}

The full JSON response is displayed for name and id as the specified
regex condition is true for both dept1 and Dept1. As two matches
are available for the specified condition, the parameters are mapped
to two separate JSONs.

Scenario: Attribute values of the attributes are retrieved from the students JSON of array that
includes the attribute name as department and the value must be only dept1.

JSON Array Response Test Result

Parse String Parameters
(input value)

Match Regex:  name  name=xyz

Name:  id  id=1234

department The exact match for both response parameters are displayed as
one match is available for name and one match for id in the
Regex: /dept1/ response that meets the mentioned condition.

 Advanced JavaScript: Use this if you require any custom JavaScript to parse any kind of data
returned by a web service. If a function is an array, the order of the parameters under Response
Parameters is significant. However, the order is not significant for JSON as it maps to the same
name. The following is an example script for parsing the response with Advanced: Javascript:

90 Setting Up a Basic Access Manager Configuration

 Scenario: A JavaScript is written to retrieve the attribute and customize it based on the
requirement. For adding the email parameter value, {P1} as input parameter is specified. A test
value for {P1} as example is added.

Script Response Test result

Parameters

function Param1 Param1 : {

main(Response_As_Is, "id": 123,
{P1}) { Param2 "mail": " [email protected]"
var jsonRes = }
JSON.parse(Response_As
_Is); Param2: {
var p1Val = ""; "id": 124,
if({P1} instanceof "mail": "[email protected]"
Array) { }
var arrElem =
{P1}[1]; The response from the REST web service is modified to
if(arrElem != return the array of students JSON that contains id and
undefined) { mail. The mail attribute is modified with the input
p1Val = arrElem; parameter values. In this scenario, the result of the
} JavaScript is an array of JSONs. Hence, the response
} else { parameters param1 and param2 are mapped with
p1Val = {P1}; each JSON (in the same order).
}
var arrResult = []; You can change the order of Response Parameters by
for(i = 0;i< using up and down arrow. The values are mapped
jsonRes["students"].le based on the order you specify. For example, the order
ngth -1; i ++) { of Response Parameters is as follows:
var jsonTemp = {};
jsonTemp.id =  param2
jsonRes["students"][i]  param1
["id"];
jsonTemp.mail = The output in the Results window displays:
jsonRes["students"][i]
["students"] + p1Val; param2 : {"id": 1234, "mail": "
[email protected]"
arrResult.push(jsonTem }
p);
} param1: {id": 124,"mail":
return arrResult; "[email protected]"
} }

 XML Parse with XPath: You can use this if the web service response is in the form of XML, and
you require to provide the XPath to extract the attribute from the xml based on the standard
XPath format.
Sample Response in xml format (Response_As_Is): The following is a sample response that is
sent by a REST web service:

Setting Up a Basic Access Manager Configuration 91

 <bookstore>
<book>
<title lang="en">
Harry Potter
</title>
<price>
29.99
</price>
</book>
<book>
<title lang="sp">
Learning XML
</title>
<price>
40
</price>
</book>
<book>
<title lang="dt">
ABCD
</title>
<price>
100
</price>
</book>
</bookstore>

XPath Scenario Response Test Result

Parameter

/bookstore/ All values are retrieved from title nodes in test test=[Harry Potter,
book/title/text() the xml response. Learning XML, ABCD]

/bookstore/ The value is retrieved from title nodes test test=Harry Potter
book[1]/title/ within the first book node in the xml
text() response.

/bookstore/ The complete title node is retrieved within test <title

book[1]/title the first book node in the xml response. lang="en">
Harry Potter
</title>

Response Parameters: When you select a response parsing function, you require to specify an
output parameter under Response Parameters to get the required parameter mapped to the output
parameter. You can use the parameter name specified under Response Parameters while configuring
virtual attributes.

2.3.4.9 Sample JavaScripts with Examples

The following section provides sample JavaScripts with examples. These are used in the Virtual
Attributes section.

92 Setting Up a Basic Access Manager Configuration

Example 1:
Consider a scenario where a service provider wants to append PID with an attribute partnerId. For
example: PID: P1.
To achieve this, fetch a user’s partnerId by using their existing “givenName” LDAP attribute (available
from the logged in user store) from the external LDAP repository. Now, add a string “PID:” to it. Later,
send the value in web servers through the Identity injection policy.
Solution: The solution is as follow:
Creating a Data Source:
1 Configure an LDAP data source with name “dsLdap”. Specify the connection properties. Test
the connection.
2 Import the secure LDAP certificate to Identity Server trust store using the create Data Source
screen.
3 Click Update All to update Identity Servers.

Creating an Attribute Source:

1 Click Devices > Identity Server > Shared Settings > Virtual Attributes > Attribute Source. Create an
attribute source with name “dsLdapAttrSrc”.
2 Select data source name “dsLdap”.
3 Add input parameter %P1%. Map it to the LDAP attribute: givenName.
4 Add a Filter: name=%P1%.
5 Add output parameter: partnerID
6 Test Filter: Test the input values.

Creating a Virtual Attribute:

1 Click Devices > Identity Server > Shared Settings > Virtual Attributes > Virtual Attribute. Create a
virtual attribute with name “partnerID”.
2 Add input parameter P1. Map it to dsLdapAttrSrc:partnerID (the attribute source that
you created in Step 1 of the creating an Attribute Source section).
3 In Step 2: Provide query and output parameters, specify the following script:

function main(P1){
return "PID:"+P1;
}
4 Test the script. The results return: PID: P1. For example, if partnerID=part123, then, the test
result is PID:part123.
5 Update Identity Server.
6 Use it in the Identity injection policy.

Example 2:
Consider a scenario where the authenticated user, named Carlos, is a manager and has
administrator rights to a protected human resource application. When Carlos accesses this
application, his roles must be passed to the application.

Setting Up a Basic Access Manager Configuration 93

 In this scenario, Carlos has a local LDAP attribute isManager and has roles of a recruiter and an
employee. He also has a local LDAP attribute groupmembership, which contains the string admins
(for example, adminsRecruitmentDep, adminsPoliciesDep).
Solution: Create a virtual attribute, App1Admin.
1. In Step1: Provide input parameters, select the following input parameters:
 P1: is mapped to LDAP attribute isManager
 P2: is mapped to LDAP attribute groupmembership
 P3: is mapped to LDAP attribute role value
2. Use the following code in Step 2: Provide a modification function > Advanced Javascript:
function main(P1, P2, P3){
if(P1 == 'true' && (/admins/i.test(P2) == true)){
return P3;
}else{
return 'NA';
}
}
3. To test JavaScript, click + and add multiple test values. Specify the following test values:
 P1: true
 P2: adminsRecruitmentDep
 P3: recruiter,employee
Output: The output is a multi-valued virtual attribute recruiter,employee.
In the function, /admins/i.test(P2) == true, /admins/i is a regular expression and test is a JavaScript
in-built function. This function tests the regular expression in the string passed as the input
parameter. The function returns true if the string contains the required pattern.

Example 3:
Consider a scenario where an Access Manager user wants to access Amazon Web Services (AWS).
AWS has multiple roles and each AWS role can have various access rights or policies assigned to it.
Based on the level of access, you can access authorized Amazon services. This information about
roles must be sent dynamically by Access Manager to AWS to provide single sign-on to the Access
Manager user.
For more information about AWS configuration, see Section 4.2.12, “Integrating Amazon Web
Services with Access Manager,” on page 670.
In this scenario, you have a constant value created using <Role ARN, Trusted SAML Provider ARN>
mapped to Remote AWS attribute Role (this value is the AWS format).
Suppose you have configured the admin and finance roles in AWS. The following are role ARNs:
 For admin: arn:aws:iam::638116851885:role/admin
 For finance: arn:aws:iam::638116851885:role/finance

For admin role, send the following: arn:aws:iam::638116851885:role/

admin,arn:aws:iam::638116851885:saml-provider/NAMIDP

94 Setting Up a Basic Access Manager Configuration

For finance role, send the following: arn:aws:iam::638116851885:role/
finance,arn:aws:iam::638116851885:saml-provider/NAMIDP
In this example, to dynamically generate the AWS role, use the LDAP attribute Department Name in
the user store. For the admin user, the department name is admin. For the finance user, the
department name is finance. To make department name available as an LDAP attribute, ensure that
you enable personal profile. Click Identity Servers > Edit > Liberty > Web Service Provider.
Solution: Create a virtual attribute with the following information:
When the user logs in, the department name (finance) is fetched for the respective user and
appended with the constant value of the role ARN. This value is then concatenated with the trusted
SAML provider ARN in the following format: arn:aws:iam::638116851885:role/
admin,arn:aws:iam::638116851885:saml-provider/NAMIDP
Map this virtual attribute with the AWS Remote Attribute role.
1. In Step1: Provide input parameters, select P1 parameter value as Department Name (Personal
Profile).
2. Use the following code in Step 2: Provide a modification function > Advanced Javascript:
function main(P1){
var role_arn='arn:aws:iam::638116851885:role/'
var provider_arn=',arn:aws:iam::638116851885:saml-provider/
MyIDP_184-142';
var aws_role;
aws_role = role_arn+P1+provider_arn;
return aws_role;
}
3. To test JavaScript, click the + and add multiple test values. Specify the test value of P1: finance.
Output: arn:aws:iam::638116851885:role/
finance,arn:aws:iam::638116851885:saml-provider/NAMIDP.

Example 4:
You want to send the groups associated with the user to a service provider named cloudsp. However,
you want to send only the groups relevant to that service, and not the complete group DN. Check for
a function that checks if the group cn starts with “cloudsp”. If available, send it to the group cn.
In this scenario, the cn of the groups relevant to cloudsp start with “cloudsp”. For example,
"cn=cloudspa,ou=group,o=mycompany". So, when a cloudsp user authenticates at Identity Server,
you need to extract all cn values from the local LDAP attribute groupMembership and filter only
those names starting with cloudsp and send it in assertion to cloudsp.
Solution:
1. In Step1: Provide input parameters, select P1 as an attribute which has the groups.
2. Use the following code in Step 2: Provide a modification function > Advanced Javascript:

Setting Up a Basic Access Manager Configuration 95

 function main( P1 ){
return mapGroups(P1);
}

function mapGroups(attribute){
var result = [];
if(attribute instanceof Array){
var j =0;
for(var i=0; i<attribute.length; i++){
var grp = checkGroup(attribute[i]);
if( grp != 'NA')
result[j++] = grp;
}
}else{
var grp = checkGroup(attribute);
if( grp != 'NA')
result[0] = grp;
}
return result;
}

function checkGroup(group){
if(/^cn=cloudsp.*,/.test(group) == true){
var startindex = 3;// it starts with cn
var endindex = group.indexOf(",");
return group.substring( startindex, endindex);
}else
return 'NA';
}
3. To test JavaScript, click the + and add multiple test values. Specify the test values:
cn=cloudspgroupa,ou=group,o=mycompany
cn=cloudspgroupb,ou=group,o=mycompany
cn=cloudspgroupk,ou=group,o=mycompany
cn=testgroupa,ou=group,o=mycompany
Output:
cloudspgroupa
cloudspgroupb
cloudspgroupk
Explanation:
The JavaScript in-built string function substring is used to extract the cn value from the group./
^cn=cloudsp.*,/.test(group) is a regular expression which matches a string that starts with cloudsp. It
has 0 or more characters followed by a comma (,).

Example 5:
(Utility Function Reuse) Consider a scenario where the Identity Server roles are in the format
companyX:rolename. A service provider abc wants the roles in the rolename format and in
upper case.

96 Setting Up a Basic Access Manager Configuration

To achieve this, remove 'companyX:' from each role and convert each of them into upper case for
sending them to the protected web server. Each role is specified as companyX:rolename.
For example, companyX:admin, companyX:guest.
Solution:
1. In Step 1: Provide input parameters, select P1: All Roles.
2. Use the following code in the Step 2: Provide a modification function > Advanced Javascript:
Copy the JavaScript from the following pre-defined functions: Remove Substring and To
upperCase.
Remove Substring function:
function findReplace(attribute, findString, replaceString){
var result;
if(attribute instanceof Array){
result = [];
for(var i=0; i<attribute.length; i++){
result[i]
=attribute[i].split(findString).join(replaceString);
}
}else{
result = attribute.split(findString).join(replaceString);
}
return result;
}
To upperCase function:
function convertToUpperCase (attribute){
var result ;
if(attribute instanceof Array){
result = [];
for(var i=0; i<attribute.length; i++)
result[i] = attribute[i].toUpperCase();
}else{
result = attribute.toUpperCase();
}
return result;
}
Now, customize the code. In the Substring to remove parameter for findReplace (), specify
companyX:

Setting Up a Basic Access Manager Configuration 97

 function main(P1){
return convertToUpperCase(findReplace (P1, 'CompanyX:'));
}

function findReplace(attribute, findString, replaceString){

var result ;
if(attribute instanceof Array){
result = [];
for(var i=0; i<attribute.length; i++){
result[i]
=attribute[i].split(findString).join(replaceString);
}
}else{
result = attribute.split(findString).join(replaceString);
}
return result;
}

function convertToUpperCase (attribute){

var result;
if(attribute instanceof Array){
result = [];
for(var i=0; i<attribute.length; i++)
result[i] = attribute[i].toUpperCase();
}else{
result = attribute.toUpperCase();
}
return result;
}

3. To test JavaScript, add the test values in P1: 'companyX:admin', 'companyX:guest'.Output:

ADMIN, GUEST.

Example 6:
Consider a scenario where you do not want to modify an attribute value that is retrieved from an
external source. To send the same attribute value in the assertion to a federated provider or in a
policies, perform the following steps:
1. Click Devices > Identity Server > Shared Settings > Virtual Attributes > Virtual Attribute.
2. In Step1: Provide input parameters, select P1, and map it to an attribute retrieved from an
external source.
3. In Step 2: Provide a modification function, select Advanced JavaScript, and specify the following
script:
function main(P1){
return P1;
}
4. Test the script. The results returns the value of the attribute source specified as P1.
5. Update Identity Server.

98 Setting Up a Basic Access Manager Configuration

2.3.4.10 Troubleshooting User Attribute Retrieval and Transformation
For troubleshooting information, see Section 32.13, “Troubleshooting User Attribute Retrieval and
Transformation,” on page 1389.

2.3.4.11 User Attribute Retrieval and Transformation Limitations

 For LDAP and database sources, the multi-valued input parameters are not supported in the
attribute source. If you input a multi-valued parameter, only one value is picked for the
calculation.
 You cannot use the existing Identity server user stores directly as an attribute source. You must
create a separate data source to use the user stores.
 You cannot edit or store any attribute value permanently in the existing LDAP attributes, shared
secret attributes, or external database by using virtual attributes.
 SSL communication with SQL and Oracle databases that are used by virtual attributes (data
sources) is not supported.

2.3.5 Adding Authentication Card Images

Each authentication contract and managed card template must have a card associated with it.
To add new images, the image files must be available from the workstation where you are
authenticated to Administration Console. Images must fall within the size bounds of 60 pixels wide
by 45 pixels high through 200 pixels wide by 150 pixels high.To add a card image:
1 Click Devices > Identity Servers > Shared Settings > Authentication Card Images.
2 Click New.
3 Specify the following details:
Name: Specify a name for the image.
Description: Describe the image and its purpose.
File: Click Browse, locate the image file, and click Open.
Locale: Select the language for the card or select All Locales if the card can be used with all
languages.
4 Click OK.
5 If you did not specify All Locales in Locale, continue with Section 2.3.6, “Creating an Image Set,”
on page 100.

Setting Up a Basic Access Manager Configuration 99

 2.3.6 Creating an Image Set
You can create card images for specific locales as well as a default image for all locales. The images
need to be placed in an image set that allows the browser to display the image associated with the
requested locale. If the browser requests a locale for which you have not defined an image, the All
Locales image is displayed. If an All Locales image is not available, the browser displays the Image not
Available card.

To add an image to the set, perform the following steps:

1 Click Devices > Identity Servers > Shared Settings > Authentication Card Images.
2 Click the card image.
3 Click New and specify the following details:
File: Click Browse, then browse to the location of the file.
Locale: Select the locale from the list.
4 Click OK.

2.3.7 Metadata Repositories

Large scale federations have more than 100+ identity and or service providers and it is a tedious task
to establish bi-lateral relationships with Access Manager. You as an identity provider can now
configure several identity providers and service providers by using a multi-entity metadata file
available in a central repository. The identity and service providers can maintain a single metadata
file containing metadata of all the approved partners. Identity providers and service providers
submit their metadata that includes specifications of services offered (SAML 1.1 and SAML 2.0) and
any other information. This feature is available only for SAML 1.1 and SAML 2.0.
For example, XYZ is an e-book store and several e-book stores, which are either identity providers or
service providers, are partners of XYZ. Hence, XYZ maintains a single metadata file that contains
metadata of all other stores. ABC an e-book identity provider wants to establish a federation with
many other e-book stores. Hence, ABC partners with XYZ by sharing its metadata and XYZ in turn
shares the metadata XML file. ABC imports the XML file available publicly on the internet (for
example, http://xyz.commonfederation.org/xyz-metadata.xml) and establishes trusts with others in
the federation, which includes XYZ’s trusted provider sites.

2.3.7.1 Creating Metadata Repositories

1 Click Devices > Identity Servers > Shared Settings > Metadata Repositories.
2 Click New and specify the following details:
Name: Specify a name for the metadata repository.
Description: Specify the description of the metadata repository.
Source: Select the source from which you want to import the metadata file.
 To specify the URL location of the XML file in URL, select Metadata URL.
 To specify the path of the XML file in File, select Metadata File.
3 Click Finish.

100 Setting Up a Basic Access Manager Configuration

 The details of the metadata such as the number of identity providers and service providers
available in the metadata and expiry date of the metadata are displayed.
You can select the metadata repository and click Delete to delete the repository. If the metadata
file is in use, you cannot delete it. Delete the trusted provider first and then delete the
metadata file.
4 Select All to see a list of entities. If the entity is supporting it the respective protocol will be
checked.
When the metadata repositories are imported, the entities available in the metadata repository can
be assigned as trusted provider to any of the Identity Server clusters. To create trusted providers, see
Section 2.7.3, “Managing Trusted Providers,” on page 191.

2.3.7.2 Reimporting Metadata Repositories

Reimport the metadata repository to get the updated XML.
1 Click Devices > Identity Servers > Shared Settings > Metadata Repositories.
2 Click the metadata repository you created and click Reimport.
3 Specify the URL location of the XML file in URL and click Next.
The page displays the following information:
New Entities added to the repositories: If the entities are updated or deleted and are assigned
as trusted providers to an Identity Server cluster, the Identity Server cluster name is displayed in
brackets next to the entity ID.
Entities Deleted from the repositories: If the entity is updated and is assigned as a trusted
provider to an Identity Server cluster, that trusted provider will be updated. You must update
Identity Server cluster for the changes to take effect.
Entities Updated in the repositories: If an entity is deleted and was assigned as trusted
provider to an Identity Server cluster, the link between the trusted provider and the metadata
repository entity is deleted.

NOTE: The corresponding trusted provider is not deleted. Delete the trusted provider manually.

4 Click Finish to apply the changes.

2.3.8 Configuring User Matching Expressions

When a service provider receives an assertion from a trusted identity provider, the service provider
tries to identify the user. You can configure a service provider to perform one of the following
actions:
 Accept that the assertion contains a valid user and authenticate the user locally with a
temporary identity and account. When a user logs out, the account and identity are destroyed.
 Use the attributes in the assertion to match a user in the local user store. When you want the
service provider to take this action, you need to create a user matching expression.
 Use the attributes in the assertion to match a user in the local user store and when the match
fails, create an account (provisioning) for the user in the local user store of the service provider.
When you want the service provider to take this action, you need to create a user matching
expression.

Setting Up a Basic Access Manager Configuration 101

 The user matching expression is used to format a query to the user store based on attributes
received in the assertion from the identity provider. This query must return a match for one user.
 If the query returns a match for multiple users, the request fails and the user is denied access.
 If the query fails to find a match and you have selected provisioning, the service provider uses
the attributes to create an account for this user in its user store. If you have not selected
provisioning, the request fails and the user is denied access.
The user matching expression defines the logic of the query. You must know the LDAP attributes that
are used to name the users in the user store in order to create the user’s distinguished name and
uniquely identify the users.
For example, if the service provider user store uses the email attribute to identify users, the identity
provider must be configured to send the email attribute. The service provider uses this attribute in a
user matching expression to find the user in the user store. If a match is found, the user is granted
access. If the user is not found, that attribute can be used to create an account for the user. The
assertion must contain all the attributes that the user store requires to create an account.
To create a user matching expression, perform the following steps:
1 Click Devices > Identity Servers > Shared Settings > User Matching Expressions.
2 Click New or click the name of an existing user matching expression.
3 Specify a name for the user lookup expression.
4 Click the Add Attributes icon (plus sign) and select attributes to add to the logic group. (Use the
Shift key to select several attributes.)
5 Click OK.
6 To add logic groups, click New Logic Group.
The Type drop-down (AND or OR) applies only between groups. Attributes within a group are
always the opposite of the type selection. For example, if the Type value is AND, the attributes
within the group are OR.
7 Click the Add Attributes icon (plus sign) to add attributes to the next logic group and click OK.
8 Click Finish.
9 (Conditional) If you selected attributes from the Custom, Employee, or Personal profile, enable
the profile so that the attribute can be shared.
9a Click Servers > Edit > Liberty > Web Service Provider.
9b Select the profiles that need to be enabled, then click Enable.
9c Click OK and then update Identity Server.

2.3.9 Configuring Advanced Authentication Server

To integrate NetIQ Advanced Authentication with Access Manager, you must configure the Advanced
Authentication server details in Access Manager.
For step-by-step details for integrating Access Manager with Advanced Authentication, see Multi-
Factor Authentication Using Advanced Authentication.

102 Setting Up a Basic Access Manager Configuration

Perform the following steps to configure Advanced Authentication server:
1 Click Devices > Identity Servers > Shared Settings > Advanced Authentication.
2 Specify the following details:

Field Description

Server Specify the scheme, domain name or IP address, and port of the Advanced
Domain Authentication server.

Tenant Specify the name of the tenant that you want to use.
Name
This field populates the TOP tenant of Advanced Authentication by default. You can
(Access specify another tenant name that you want to use.
Manager 4.5
Service Pack
2 and later)

NOTE: When using the Plug-in-based methods, skip to Step 5 on page 104.

3 (Required only for OAuth-based approach) Select Integrate using OAuth under OAuth Event
Configuration.
4 (Required only for OAuth-based approach) Specify the following details:

Field Description

Event Name Specify an event name. This event name must be identical to the event name specified
in the Advanced Authentication administration portal.

Client ID Specify the client ID that was generated while creating the OAuth 2.0 event in the
Advanced Authentication administration portal.

Client Secret Specify the client secret that was generated while creating the OAuth 2.0 event in the
Advanced Authentication administration portal.

Webauth To use the Virtual Smartcard method, select Use the Advanced Authentication Virtual
Domain Smartcard. This populates the Webauth Domain URL.

(Access For example, if aaserver.domain.com is the DNS name of your web server then
Manager 4.5 webauth.domain.com is populated in Webauth Domain.
Service Pack
1 and later) When you enable this option, all the requests from Identity Server to OSP are
redirected to webauth.domain.com instead of aaserver.domain.com.

NOTE: The Virtual Smartcard method must be configured in the Advanced

Authentication server.

Access Manager uses the endpoint links to retrieve token and user details from the Advanced
Authentication server. These are default endpoint links. If the values of the URIs change
because of modification of the Advanced Authentication authorization server, then you can
change the values here.

Setting Up a Basic Access Manager Configuration 103

 Field Default Value Description

Authorization /osp/a/TOP/auth/oauth2/grant Access Manager uses this URL to retrieve the

URL authorization code from the Advanced
Authentication server.

Token URL /osp/a/TOP/auth/oauth2/ Access Manager uses this URL to exchange the
authcoderesolve authorization code with the access token.

User Info URL /osp/a/TOP/auth/oauth2/ Access Manager sends the access token to this
getattributes URL to get the user details from the Advanced
Authentication server.

The fields under Integration URLs are auto-populated after you specify the server domain
address.

IMPORTANT: If the values are not auto-populated then specify the default values as mentioned
in the following table.

Field Default Value Description

Enrollment Page /account/basic If the user is not enrolled in the Advanced

URL Authentication server, then Access Manager
uses this URL to redirect the user to the
enrollment page.

Sign Data URL /osp/a/TOP/auth/oauth2/sign Access Manager uses this URL to retrieve the
signed data from the Advanced Authentication
server.

5 Click Apply.
6 Proceed with Section 4.3.3, “NetIQ Advanced Authentication,” on page 707 to create Advanced
Authentication classes.

2.3.10 Configuring Self Service Password Reset Server Details in Identity

Server
Perform the following steps to specify the Self Service Password Server details:
1 Click Devices > Identity Server > Shared Settings > Self Service Password Reset.
2 Select Integrate with Self Service Password Reset (SSPR).
3 Specify the following details under Server Configuration:
Published SSPR URL: Select http or https and specify the Self Service Password Reset server’s IP
address or DNS name with the port number. If Self Service Password Reset is configured behind
Access Gateway, then specify Access Gateway's Published URL for Self Service Password Reset.
For example, specify https://www.b2c.com/sspr/.
API User Name: Protected web services that require authentication through a user name and
password use the secret name as user name. The secret name is generated while configuring
the Self Service Password Reset server. For example, specify NAMSECRET in API User Name.

104 Setting Up a Basic Access Manager Configuration

 API Password: Protected web services that require authentication through a user name and
password use a secret key as password. The secret key is generated while configuring the Self
Service Password Reset server. For example, specify pass@123 in API Password.
4 Click the + icon under Integration Links to see URLs associated with the specified Self Service
Password Reset server.

IMPORTANT: Integration Links displays default URLs. These URLs must be modified to match the
URLs specified on the Self Service Password Reset server.

If you modify the integration links in the Self Service Password Reset server then you must
specify the same integration links in SSPR Portal Links and REST APIs. The values specified in
Integration Links come after Published SSPR URL to form a destination path.

IMPORTANT: In some of the default URLs, forwardURLs are appended to ensure that the user is
forwarded to correct URLs after performing the corresponding tasks.

User Profile URL: If a forwardURL is provided, the user is redirected to that URL after updating
user profile in user portal page. For example, if User Profile URL is set to /
private?forwardURL=https://idp.b2c.com:8443/nidp/portal, then the user is
directed to that URL after profile update.
User Registration URL: If a forwardURL is provided, the user is redirected to that URL after
registering as a new user on B2C portal page. For example, if User Registration URL is set to /
private?forwardURL=https://idp.b2c.com:8443/nidp/portal, then the user is
directed to that URL after registration.
Auto Registration URL: It automatically registers users when users log in using social
authentication. It compares the user specified attributes to the stored attributes. Specify /
public/newuser/profile/Social.
Forgot Password URL: If a forwardURL is provided, the user is redirected to that URL after
password reset. For example, if Forgot Password URL is set to /
private?forwardURL=https://idp.b2c.com:8443/AGLogout, then the user is directed
to that URL after the user resets password.

NOTE: Forgot Password URL is not accessible if the Logout after password change option is
enabled in Change Password module of Self Service Password Reset.

Health API: It is used to obtain the health status of the Service Password Reset server. The
default URL is /public/rest/health.
Back Channel Request Signing API: Access Manger uses this API to obtain information from Self
Service Password Reset server. The default URL is /public/rest/signing/form.
Connection Timeout: It is the time specified to establish the connection with Self Service
Password Reset server. The connection must establish within the specified time.
Read Timeout: It is the time specified to obtain information from the Self Service Password
Reset server after establishing the connection. Access Manager must obtain information within
the specified time.

Setting Up a Basic Access Manager Configuration 105

 IMPORTANT: Ensure that these URLs are specified in the Self Service Password Reset white
list. To specify these URLs in white list navigate to Self Service Password Reset > Settings >
Security > Web Security > Whitelist.
 If a forwardURL is not provided then the default URLs are used. To see default URLs,
navigate to Self Service Password Reset > Settings > Application > Forward URL.

5 Click Apply Changes.

2.4 Configuring Access Gateway

The basic Access Gateway configuration procedures consists of the following tasks:
 Section 2.4.1, “Configuring a Reverse Proxy,” on page 106
 Section 2.4.2, “Configuring a Public Protected Resource,” on page 108
 Section 2.4.3, “Configuring Access Gateway for Authentication,” on page 109
 Section 2.4.4, “Setting Up Policies,” on page 111

2.4.1 Configuring a Reverse Proxy

You can protect your web services by creating a reverse proxy. A reverse proxy acts as the front end
to your web servers in your DMZ or on your intranet. It off-loads frequent requests, thereby freeing
up bandwidth and web server connections. It also increases security because the IP addresses and
DNS names of your web servers are hidden from the Internet. A reverse proxy can be configured to
protect one or more proxy services.
To create a reverse proxy, you must create at least one proxy service with a protected resource. You
must supply a name for each of these components. Reverse proxy names and proxy service names
must be unique to Access Gateway because they are configured for global services such as IP
addresses and TCP ports. For example, if you have a reverse proxy named products and another
reverse proxy named library, only one of these reverse proxies can have a proxy service named
corporate.

Protected resource names need to be unique to the proxy service, but they don’t need to be unique
to Access Gateway because they are always accessed through their proxy service. For example, if you
have a proxy service named account and a proxy service named sales, they both can have a
protected resource named public.

106 Setting Up a Basic Access Manager Configuration

What You Need To Know Example Your Value

Name of Identity Server cluster idp-corporate _______________________

DNS name of Access Gateway mytest.com ______________________

Web server information

IP address 10.15.70.21 ______________________

DNS name mywebserver.com ______________________

Names you need to create

Reverse proxy name mycompany ________________________

Proxy service name company ________________________

Protected resource name public ________________________

This first reverse proxy is used for authentication. You need to configure the proxy service to use the
DNS name of Access Gateway as its Published DNS Name, and the web server and the resource on
that web server need to point to the page you want displayed to the users when they first access
your website. You can use Access Gateway configuration options to allow this first page to be a
public site with no authentication required until the users access the links on the page, or you can
require authentication on this first page.
Figure 2-2 Basic Configuration

Server 1 Server 3
Identity Server LDAP Directory

Server 2 Server 4
Access Gateway Web Server

Public DNS Name: DNS Name:

www.mytest.com mywebserver.com
IP Address: IP Address:
10.10.167.53:80 10.15.70.21

Complete the following steps to first configure a protected resource as a public resource and then to
modify the configuration to require authentication:
1 Click Devices > Access Gateways, Edit > Reverse Proxy / Authentication.
2 In Identity Server Cluster, select the configuration you have assigned to Identity Server.
This sets up the trust relationship between Access Gateway and Identity Server that is used for
authentication.
3 In Reverse Proxy List, click New, specify a display name for the reverse proxy, and click OK.
4 Enable a listening address.

Setting Up a Basic Access Manager Configuration 107

 Listening Address(es): A list of available IP addresses. If the server has only one IP address, only
one is displayed and it is automatically selected. If the server has multiple addresses, you can
select one or more IP addresses to enable. You must enable at least one address.
TCP Listen Options: Options for configuring how requests are handled. You cannot set up
listening options until you create a proxy service.
5 Ignore the SSL configuration options.
This configuration does not set up SSL. For SSL information, see Enabling SSL Communication.
6 Configure a listening port.
Non-Secure Port: Select 80 that is the default port for HTTP.
Secure Port: This is the HTTPS listening port. This port is unused and cannot be configured until
you enable SSL.
7 In Proxy Service List, click New.
8 Specify the following details:

Field Description

Proxy Service Name A display name for the proxy service.

Published DNS Name The DNS name you want the public to use to access your site. For this first
proxy server, the DNS name must resolve to Access Gateway IP address that
you selected as the listening address. For example, in Figure 2-2, this name
would be www.mytest.com.

Web Server IP Address The IP address of your web server. This is the web server with content that
you want to share with authorized users and protect from others. In Figure
2-2, this is Server 4, whose IP address is 10.15.70.21.

Host Header The name you want to send in the HTTP header to the web server. This can
either be the published DNS Name (the Forward Received Host Name
option) or the DNS name of the web Server (the Web Server Host Name
option).

Web Server Host Name The DNS name that Access Gateway must forward to the web server. This
option is not available if you select Forward Received Host Name for the
Host Header option. The name you use depends upon how you have set up
the web server. If your web server has been configured to verify that the
host name in the header matches its name, specify that name here. In
Figure 2-2, the Web Server Host Name is mywebserver.com.

9 Click OK.
10 Continue with Section 2.4.2, “Configuring a Public Protected Resource,” on page 108.

2.4.2 Configuring a Public Protected Resource

The first protected resource discussed in this configuration is configured to be a public resource. For
information about how to set up authentication for a protected resource, see Section 2.4.3,
“Configuring Access Gateway for Authentication,” on page 109.
1 In Proxy Service List, click [Name of Proxy Service] > Protected Resources.
2 In Protected Resource List, click New, specify a name for the resource, and click OK.

108 Setting Up a Basic Access Manager Configuration

 3 In the Contract field, select None.
The Contract field must be set to None. This is makes this resource a public resource.
4 Configure URL Path List.
The default path is /*, which allows access to everything on the web server. Modify this if you
need to restrict access to a specific directory on your web server.
 To delete the default path, select the check box next to the path, then click Delete.
 To edit a path in the list, click the path, modify it, then click OK.
 To add a path, click New, specify the path, then click OK. For example, to allow access to
the pages in the public directory on the web server, specify the following path:
/public/*
5 Click OK.
6 In the Protected Resource List, verify that the protected resource you created is enabled, then
click OK.
7 Click Devices > Access Gateways.
8 Click Update > OK.
The system sends configuration changes to the server and writes the configuration to the
configuration data store. When the update has completed successfully, the server returns the
status of Current.
To save the changes to the configuration store without applying them, do not click Update.
Instead, click Edit. If you have pending configuration settings, the OK button is active, and the
configuration page indicates which services will be updated. Click OK to save these changes to
the configuration store. The changes are not applied until you Update on Access Gateways page.
9 To update Identity Server to establish the trust relationship with Access Gateway, click Devices >
Identity Servers > Update > OK.
Wait until the Command status is Complete and the Health status is green.
10 (Optional). To test this configuration from a client browser, specify the published DNS name as
the URL in the browser. In the example illustrated in Figure 2-2, specify the following URL:
http://www.mytest.com
This must resolve to the published DNS name you specified in Step 8, and the user must be
connected to the web server through Access Gateway.
11 Continue with Section 2.4.3, “Configuring Access Gateway for Authentication,” on page 109.

IMPORTANT: You must not modify the default NAM-Service proxy service.

2.4.3 Configuring Access Gateway for Authentication

The procedures in Configuring a Reverse Proxy and Configuring a Public Protected Resource set up
Access Gateway to protect your web server by hiding its IP address and DNS name from Internet
users. The procedure does not require the user to log in before accessing resources on the web

Setting Up a Basic Access Manager Configuration 109

 server. This section explains how to configure Access Gateway so that the users are required to
provide login credentials before they access to a protected resource. This configuration consists of
two parts:
 Section 2.4.3.1, “Verifying Time Synchronization,” on page 110
 Section 2.4.3.2, “Enabling Trusted Authentication,” on page 110

2.4.3.1 Verifying Time Synchronization

The time must be synchronized between Identity Server and Access Gateway or set so the time
difference is within one minute of each other for trusted authentication to work.
For Identity Server or Linux Access Gateway Service, use YaST to verify the time settings. For a
Windows Access Gateway Service, use the Date and Time option in the Control Panel. If you have a
Network Time Protocol server, configure the Access Manager machines to use it.
For an Access Gateway Appliance, complete the following steps:
1 Click Devices > Access Gateways> Edit > Date & Time.
2 Select a method you want to use for time:
Set Date & Time Manually: Allows you to select the current time. Click this option to select
year, month, day, hour, and minute in your current time zone, then click OK.
Set Up NTP: Allows you to specify the IP address of an NTP server. Click Set Up NTP. Use the
public pool.ntp.org server or click New, then specify the IP address of an NTP server. To accept
the configuration, click OK.
If the time on the machine is wrong by more than an hour, use both methods to set the time.
Set it manually first, and then configure it to use NTP.
3 In the Time Zone section, select your time zone, then click OK.
Regardless of the method you used to set the time, you must select a time zone.
4 Click OK.
5 Click Devices > Access Gateways > Update > OK.
Continue with “Enabling Trusted Authentication” on page 110.

2.4.3.2 Enabling Trusted Authentication

Trusted authentication requires an authentication contract that specifies the type of authentication
credentials. Identity Server and Access Gateway control these authentication requirements. You do
not need to configure your web server to require authentication. Access Manager enforces the
requirements for you.
In this example, you set up an authentication contract that requires a username and a password to
access a directory on a web server.
1 Click Devices > Access Gateways, then click Edit > [Name of Reverse Proxy] > [Name of Proxy
Service] > Protected Resources > New.
2 Specify a display name for the protected resource, then click OK.
3 Select one of the following in Authentication Procedure:

110 Setting Up a Basic Access Manager Configuration

 Name/Password - Basic: Basic authentication over HTTP using a standard login page provided
by the web browser.
Name/Password - Form: Form-based authentication over HTTP.
Others are available, but for this basic setup, which does not enable SSL, select one of the
above contracts. The contract needs to match the protocol.
If these default authentication contracts are not available, you have not configured a
relationship between Access Gateway and Identity Server. See Configuring a Reverse Proxy and
select a value for the Identity Server Cluster field.
4 In URL Path List, configure the URL path to the page that this authentication contract will
protect. For the web server configuration described in Prerequisites for a Basic Access Manager
Setup, click the /* path and modify it to specify the following path:
/protected/*
5 Click OK > OK.
6 Click Devices > Access Gateways > Update > OK.
7 (Optional) To test this configuration from a client browser, log in to Access Gateway:
7a Specify the published DNS name to this resource in the browser. For example, in Figure 2-2
on page 107, you would specify the following URL:
http://www.mytest.com
7b Click the link to the protected page. This must be a link to the same page you configured in
Step 4.
Your browser must prompt you with a login page. If you selected Name/Password - Basic as
the contract, the standard login page issued by your browser is displayed. If you selected
Name/Password - Form, the default Access Manager login page is displayed.
7c Log in to Identity Server with a username and password that is stored in your LDAP
directory (Server 3 in Figure 2-2 on page 107).
You must have access to the information you have placed in the protected directory on
your web server.
If you have set up your web server to require basic authentication to access this directory,
you are prompted again for login credentials.
If you receive an error, see “Common Authentication Problems” on page 260.
8 Continue with “Setting Up Policies” on page 111.

2.4.4 Setting Up Policies

Access Gateway lets you retrieve information from your LDAP directory and inject the information
into HTML headers, query strings, or basic authentication headers. Access Gateway can then send
this information to the back-end web servers. Access Manager calls this technology Identity
Injection.
This is one of the features within Access Manager that enables single sign-on. Users are prompted
for the login credentials for one time, and Access Manager then supplies them for the resources you
have configured for Identity Injection.

Setting Up a Basic Access Manager Configuration 111

 This section explains how to set up an Identity Injection policy for basic authentication. This policy is
assigned to the third directory on your web server, which is the basic directory that your web
server has been configured to require basic authentication before allowing access.
1 Click Devices > Access Gateways > Edit > [Reverse Proxy Name] > [Proxy Service Name] >
Protected Resources > New.
2 Configure the resource for the basic directory as described in Section 2.1, “Prerequisites for a
Basic Access Manager Setup,” on page 43:
2a For the contract, select Name/Password - Basic or Name/Password - Form.
2b For the URL path, specify the path to the basic directory (/basic/*).
2c Click OK.
3 Click [Protected Resource Name] > Identity Injection.
On a new installation, the list is empty because no policies have been created.
4 In the Identity Injection Policy List section, click Manage Policies.
5 In the Policy List section, click New, then specify values for the following fields:
Name: Specify a name for the Identity Injection policy.
Type: Select Access Gateway: Identity Injection.
6 Click OK.
7 (Optional) Specify a description for the policy.
8 In the Actions section, click New > Inject into Authentication Header.
9 Set up the policy for User Name and Password:
 For User Name, select Credential Profile and LDAP Credentials: LDAP User Name.
This injects the value of the cn attribute into the header.
 For Password, select Credential Profile and LDAP Credentials: LDAP Password.
The policy must look similar to the following:

112 Setting Up a Basic Access Manager Configuration

 10 Click OK > OK > Apply Changes > Close.
11 Select the new Identity Injection policy, then click Enable > OK.
12 Click Devices > Access Gateways > Update > OK.
13 To test this configuration from a client browser, specify the published DNS name as the URL in
the browser. Click the link to the page that uses basic authentication.
You are prompted to log in. If you have set up web applications on your web server that require
login, any additional login prompts are hidden from the user and are handled by the identity
injection system.

2.5 Configuring Access Gateways Clusters

A cluster of Access Gateways must reside behind a Layer 4 (L4) switch. Clients access the virtual IP on
the L4, and the L4 alleviates server load by balancing traffic across the cluster of Access Gateways.
Whenever a user enters the URL for an Access Gateway resource, the request is routed to the L4
switch, and the switch routes the user to one of Access Gateways in the cluster, as traffic
necessitates.
Figure 2-3 illustrates the flow of a user request when Access Gateways are clustered behind an L4
switch.
Figure 2-3 Clustering Access Gateways

User Identity Server LDAP Directory

2
3
4

1 5
Web Server

L4 Switch
Clustered
Access Gateways

1. The user requests access to a protected resource by sending a request to the L4 switch. The
request is sent to one of Access Gateway servers in the cluster.
2. Access Gateway redirects the request to Identity Server for authentication. Identity Server
presents the user with a login page, requesting a user name and a password.
3. Identity Server verifies the user’s credentials with the directory.
4. The validated credentials are sent through the L4 switch to the same Access Gateway that first
received the request.
5. Access Gateway verifies the user credentials with Identity Server.
6. If the credentials are valid, Access Gateway forwards the request to the web server.

Setting Up a Basic Access Manager Configuration 113

 If Access Gateway where the user's session was established goes down, the user’s request is sent to
another Access Gateway in the cluster. This Access Gateway pulls the user’s session information
from Identity Server. This allows the user to continue accessing resources, without having to re-
authenticate.

IMPORTANT: You must not use a DNS round robin setup instead of an L4 switch for load balancing.
The DNS solution works only as long as all members of the cluster are working and in a good state. If
one of them goes down and traffic is still sent to that member, the entire cluster is compromised and
starts generating errors.

The following sections describe how to set up and manage a cluster of Access Gateways:
 Section 2.5.1, “Prerequisites for Configuring an Access Gateways Cluster,” on page 114
 Section 2.5.2, “Designing the Membership Type for a Cluster,” on page 114
 Section 2.5.3, “Configuring a Cluster,” on page 115
 Section 2.5.4, “Managing Access Gateway Cluster Configuration,” on page 116

2.5.1 Prerequisites for Configuring an Access Gateways Cluster

 An L4 switch is installed. You can use the same switch for an Identity Server cluster and an
Access Gateway cluster, provided that you use different virtual IPs.
 One or more Access Gateways is installed.
When you install a new Access Gateway, configure it to use the same Administration Console.
 Your DNS server must to be configured to resolve the published DNS names that you specify for
your proxy services to the L4 switch.
 Persistent (sticky) sessions on the L4 switch is enabled (highly recommended, but not
mandatory).

IMPORTANT: If you have created a configuration for one or more of Access Gateways you are going
to put in a cluster, you need to carefully select the primary cluster server. The current configuration
of the primary cluster server is pushed to the other servers in the cluster. If you have created
configurations for the other servers in the cluster, these configurations are overwritten.

2.5.2 Designing the Membership Type for a Cluster

You can create a cluster of all Gateway Appliances or of all Gateway Services. The Gateway Services
cluster can be either all in Linux or all in Windows.
When you create a cluster of Access Gateways that are of the same type, you can guarantee that the
user experience is always the same, regardless of which Access Gateway the user establishes a
connection to. For a list of the differences between Access Gateway Appliance and Access Gateway
Service, see Feature Comparison of Different Types of Access Gateways in the NetIQ Access Manager
4.5 Installation and Upgrade Guide.

114 Setting Up a Basic Access Manager Configuration

2.5.3 Configuring a Cluster
1 Click Devices > Access Gateways > New Cluster.
2 Specify the following details:
Cluster Name: Specify a display name for the cluster.
Type: Select the type of cluster you want to create: Gateway Appliance or Gateway Service.
Primary Cluster Server: Select the server that is to be the primary server in the cluster.
3 In the Server Name list, select the servers that you want to be members of the cluster.
You can create a cluster of one, and add additional servers later. You cannot create a cluster that
contains Access Gateway Appliances and Access Gateway Services. The cluster can contain only
one type of Access Gateway.
Each server you add to the cluster adds about 30 seconds to the time it takes to configure the
cluster because certificates must be synchronized and configuration options must be sent to
that server. If you create a very large cluster of twenty servers, it can take up to ten minutes to
configure and create the cluster.
4 Click OK.
5 After the cluster has been created, each server in the cluster needs be restarted. On the Access
Gateways page, click Update All by the name of the cluster.
6 (Conditional) If Access Gateways in the cluster have multiple network adapters or IP addresses,
you need to configure the listening address for each reverse proxy.
When you create the cluster configuration for newly added servers, the listening address is
always the IP address of eth0. If this is not the address where you want the reverse proxy to
listen for requests, click Access Gateways > Edit > [Name of Reverse Proxy], select Access
Gateway as the Cluster Member, then enable the Listening Address you want to use.
7 To configure the cluster, click Access Gateways > Edit.
A cluster of Access Gateways has the same configuration options as a single Access Gateway.
The only difference is that for some options you need to select Access Gateway to configure. For
example, the Date & Time option allows you to set the time separately for each member of the
cluster.
Applying the configuration to a cluster is slightly different. You have the option to apply the
changes to all servers in the cluster by selecting the Update All option, or to apply them to one
server at a time by selecting the Update option for each server. When you update the servers
one at time, your site remains up. For more information about the Update and Update All
options, see “Status Options” on page 325.
If you prefer to apply changes to the servers one at time, you must save the changes to the
configuration datastore on the Server Configuration page. (The OK buttons on the other
configuration pages save the changes to browser cache.) If your session times out before you
update all servers in the cluster and the changes have been saved only in browser cache, the
changes are lost and are not applied to the servers that are still in an Update status.

Setting Up a Basic Access Manager Configuration 115

 2.5.4 Managing Access Gateway Cluster Configuration
This section describes the tasks that are specific to managing the servers in a cluster:
 Section 2.5.4.1, “Creating a New Cluster,” on page 116
 Section 2.5.4.2, “Managing Access Gateway Servers in the Cluster,” on page 116
 Section 2.5.4.3, “Managing Cluster Details,” on page 117
 Section 2.5.4.4, “Editing Cluster Details,” on page 118
 Section 2.5.4.5, “Changing the Primary Cluster Server,” on page 118
 Section 2.5.4.6, “Applying Changes to Access Gateway Cluster Members,” on page 118

2.5.4.1 Creating a New Cluster

1 Click Devices > Access Gateways > New Cluster.
2 Specify the following details:
Cluster Name: Specify a display name for the cluster.
Type: Select the type of cluster you want to create: Gateway Appliance or Gateway Service.
Primary Cluster Server: Select the server that is to be the primary server in the cluster. This
field is empty until you have selected one or more servers to be members of the cluster.
3 In the Server Name list, select the servers that you want to be members of the cluster.
You can create a cluster of one and add additional servers later.You cannot create a cluster that
contains Access Gateway Appliances and Access Gateway Services. The cluster can contain only
one type of Access Gateway.
Each server you add to the cluster adds about 30 seconds to the time it takes to configure the
cluster because certificates must be synchronized and configuration options must be sent to
that server. If you create a very large cluster of twenty servers, it can take up to ten minutes to
configure and create the cluster.
4 Select the server you want to be the Primary Cluster Server.
5 Click OK.
6 After the cluster has been created, each server in the cluster needs be restarted. On the Access
Gateways page, click Update All by the name of the cluster.
For information about additional required configuration tasks, see Section 2.5.4, “Managing
Access Gateway Cluster Configuration,” on page 116.

2.5.4.2 Managing Access Gateway Servers in the Cluster

To view the servers that are currently members of clusters:
1 Click Devices > Access Gateways.
The members of a cluster are listed under the cluster name. The red double dagger symbol
identifies the server that is the primary cluster server.
2 To add a server to a cluster, select the server, then click Actions > Assign to Cluster > [Name of
Cluster].

116 Setting Up a Basic Access Manager Configuration

 A cluster cannot contain both Access Gateway Appliances and Access Gateway Services. The
cluster can contain only one type of Access Gateway.
3 To remove a server from a cluster, select the server, then click Actions > Remove from Cluster.
Usually when you delete a server from a cluster, you have discovered that traffic is lighter than
anticipated and that it can be handled with fewer machines while another cluster is
experiencing higher traffic and can benefit from having another cluster member. When the
server is removed, its configuration object maintains all the configuration settings from the
cluster. When it is added to a new cluster, its configuration object is updated with the
configuration settings of the new cluster. If your clusters are behind an L4 switch, you need to
reconfigure the switch so that the server is assigned to the correct cluster.
When a server is removed from a cluster, its Embedded Service Provider is stopped. If you are
not going to assign it to another cluster, you need to reconfigure the server so that it is
protecting resources other than the ones it protected in the cluster. When you apply the
changes by clicking Update, the Embedded Service Provider is restarted.
You cannot remove the primary cluster server unless it is the only server in the cluster. If you
need to remove the primary cluster server from a multiple server cluster, you need to assign
another the server to be the primary cluster server.
4 To modify which server is the primary cluster server, see “Changing the Primary Cluster Server”
on page 118.
5 To view detailed information about a server in the group, click the name of the server.
6 To view detailed health information about a server, click the health icon of the server.
7 Click Close.

2.5.4.3 Managing Cluster Details

Use the Cluster Details page to perform general maintenance actions on the selected cluster and to
display server information about the selected cluster.
1 Click Devices > Access Gateways > [Cluster Name].
2 View the following fields:
Name: Specifies the name of the cluster.
Description: Specifies the purpose of the cluster. This is optional, but useful if your network has
multiple Access Gateway clusters. If the field is empty, click Edit to add a description.
Primary Server: Indicates which server in the cluster has been assigned to be the primary
server.
3 To modify the information, click Edit. For more information, see “Editing Cluster Details” on
page 118.
4 To select a different Access Gateway to be the primary cluster member, click Edit.
5 To modify details about a cluster member, click the server name in the Cluster member list.
6 Click Close.

Setting Up a Basic Access Manager Configuration 117

2.5.4.4 Editing Cluster Details
Use the Cluster Detail Edit to change the name of the cluster and assign a different server to be the
primary cluster member.
1 Click Devices > Access Gateways > [Cluster Name] > Edit.
2 Modify the following fields:
Name: Specify a name for the cluster.
Description: Specify the purpose of the cluster. This is optional, but useful if your network has
multiple Access Gateway clusters.
Primary Server: Indicates which server in the cluster has been assigned to be the primary
server. To change this assignment, select the server from the drop-down list. For more
information about this process, see “Changing the Primary Cluster Server” on page 118.
3 Click OK.

2.5.4.5 Changing the Primary Cluster Server

If the current primary cluster server is down and will be down for an extended period of time, you
must select another server to be the primary cluster server
1 Click Devices > Access Gateways > [Name of Cluster] > Edit.
2 In the Primary Server list, select the name of a server, then click OK.
Wait until this configuration change has completed, before doing any other configuration
updates.
3 To update Identity Server, click Identity Servers > Update.

2.5.4.6 Applying Changes to Access Gateway Cluster Members

When you are configuring services of Access Gateway, the OK button saves the change to browser
cache except on the Configuration page. The Configuration page (Devices > Access Gateways > Edit)
provides a summary of the changes you have made. The Cancel Change column allows you to cancel
changes to individual services. When you click OK, the changes are saved to the configuration
datastore, and you no longer have the option to cancel changes to individual services.
If you don’t save the changes to the configuration datastore and your session times out or you log
out, any configuration changes that are saved to browser cache are flushed. These changes cannot
be applied to other members of the cluster because they are no longer available. To prevent this
from happening, save the changes to the configuration datastore.

118 Setting Up a Basic Access Manager Configuration

It is especially important to save the changes to the configuration datastore when you select to
update individual members one at a time rather than update all members of the cluster at the same
time. Updating members one at a time has the following benefits:
 When you update all servers at the same time, the site goes down until one server has finished
updating its configuration. If you update the cluster members one at a time, only the member
that is updating its configuration becomes unavailable.
 If you update the servers one at time, you can verify that the changes are behaving as expected.
After testing the configuration on one server, you can then apply the saved changes to the other
servers in the cluster. If you decide that the configuration changes are not behaving as
expected, you can revert to the previously applied configuration. See “Reverting to a Previous
Configuration” on page 119.
Some configuration changes cannot be applied to individual cluster members. For a list of these
changes, see “Modifications Requiring an Update All” on page 119.

Reverting to a Previous Configuration

If you have updated only one server in the cluster, you can use the following procedure to revert
back to the previous configuration.
1 Remove the server that you have applied the configuration changes from the cluster.
2 Access the Configuration page for the cluster, then click Revert.
The servers in the cluster revert to the last applied configuration.
3 Add the removed server to the cluster.
The server is configured to use the same configuration as the other cluster members.

Modifications Requiring an Update All

When you make the following configuration changes, the Update All option is the only option
available and your site is unavailable while the update occurs:
 If you change Identity Server configuration that is used for authentication (Access Gateways >
Edit > Reverse Proxy/Authentication, then select a different value for the Identity Server Cluster
option).
 If you select a different reverse proxy to use for authentication (Access Gateways > Edit >
Reverse Proxy/Authentication, then select a different value for the Reverse Proxy option).
 If you modify the protocol or port of the authenticating reverse proxy (Access Gateways > Edit >
Reverse Proxy/Authentication > [Name of Reverse Proxy], then change the SSL options or the
port options).
 If you modify the published DNS name of the authentication proxy service (Access Gateways >
Edit > Reverse Proxy/Authentication > [Name of Reverse Proxy] > [Name of First Proxy Service],
then modify the Published DNS Name option).

Setting Up a Basic Access Manager Configuration 119

 2.6 Protecting Web Resources Through Access Gateway
Access Gateway is a reverse proxy server (protected site server) that restricts access to web-based
content, portals, and web applications that employ authentication and access control policies. It also
provides single sign-on to multiple web servers and web applications by securely providing the
credential information of authenticated users to the protected servers and applications. Access
Gateway lets you simplify, secure, and accelerate your Internet business initiatives.
This section describes the following tasks:
 Section 2.6.1, “Configuration Options,” on page 120
 Section 2.6.2, “WebSocket Support,” on page 122
 Section 2.6.3, “Managing Reverse Proxies and Authentication,” on page 125
 Section 2.6.4, “Configuring Web Servers of a Proxy Service,” on page 132
 Section 2.6.5, “Configuring Protected Resources,” on page 134
 Section 2.6.6, “Configuring HTML Rewriting,” on page 146
 Section 2.6.7, “Configuring Connection and Session Limits,” on page 165
 Section 2.6.8, “Protecting Multiple Resources,” on page 170

2.6.1 Configuration Options

A typical Access Manager configuration includes an Identity Server with LDAP directories and an
Access Gateway with a protected web server. Figure 2-4 illustrates the process flow that allows an
authorized user to access the protected resource on the web server.
Figure 2-4 Accessing a Web Resource

Identy Server LDAP Directory

2
3
4

4 Identy Injecon
6 7
1
User Access Gateway Web Server Web Page
(with basic authencaon)

1. The user requests access to a resource protected by Access Gateway.

2. Access Gateway redirects the user to Identity Server, which prompts the user for a username
and password.
3. Identity Server verifies the username and password against an LDAP directory (eDirectory,
Active Directory, or Sun ONE).
4. Identity Server returns an authentication success to the browser and the browser forwards the
resource request to Access Gateway.

120 Setting Up a Basic Access Manager Configuration

 5. Access Gateway verifies that the user is authenticated and retrieves the user’s credentials from
Identity Server.
6. Access Gateway uses an Identity Injection policy to insert the basic authentication credentials in
the HTTP header of the request and sends it to the web server.
7. The web server grants access and sends the requested page to the user.
When you are setting up Access Gateway to protect web resources, you create and configure reverse
proxies, proxy services, and protected resources. The following figure illustrates the hierarchy of
these modules and the major configuration tasks you perform on each module.
Figure 2-5 Access Gateway Modules and Their Configuration Options

Module Hierarchy Configuration Options

Reverse Proxy Listening Address & Port
SSL Requirements

Web Servers
Proxy Service Caching
HTML Rewriting
Logging

URLs
Authentication Contracts and Procedures
Protected Resource Authorization
Identity Injection
Form Fill

This hierarchy allows you to have precise control over what is required to access a particular
resource, and also allows you to provide a single sign-on solution for all the resources protected by
Access Gateway. The authentication contract, authentication procedure, Authorization policy,
Identity Injection policy, and Form Fill policy are configured at the resource level so that you can
enable exactly what the resource requires. This allows you to decide where access decisions are
made:
 You can configure Access Gateway to control access to the resource.
 You can configure the web server for access control and configure Access Gateway to supply the
required information.
 You can use the first method for some resources and the second method for other resources or
use both methods on the same resource.

Setting Up a Basic Access Manager Configuration 121

 2.6.2 WebSocket Support
The WebSocket protocol is an extension to the HTTP 1.1 protocol to enable two-way communication
between a client and a server. It is an independent TCP-based protocol. The protocol has two parts -
handshake and data transfer. HTTP servers interpret its handshake as an upgrade request. By default,
the WebSocket protocol uses port 80 for regular WebSocket connections and port 443 for
WebSocket connections tunneled over Transport Layer Security (TLS).
The protocol works in the following sequence:
1. The client sends an HTTP upgrade request to the server through Access Gateway to establish a
communication channel between the client and the server. (WebSocket protocol handshake)
2. The server sends an HTTP 101 response to the requesting client through Access Gateway. When
the client receives the response, the HTTP connection is upgraded to WebSocket.
3. Bidirectional data exchange happens between the server and the client over the WebSocket
connection.
4. Either of the participant in the data exchange requests to terminate the WebSocket connection.
One participant sends a Close request to the other participant and the connection is
terminated.
WebSocket enables Access Gateway to accept an HTTP upgrade request from a client.
The following diagram illustrates the flow of messages among the client, Access Gateway, and the
server in a WebSocket communication:

122 Setting Up a Basic Access Manager Configuration

 Figure 2-6 WebSocket Communication

WebSocket Client Access Gateway WebSocket Server

HTTP Upgrade request

HTTP Upgrade request

HTTP 101 response

HTTP 101 response

Bidirectional WebSocket messages

Bidirectional WebSocket messages

Close

Close

Close response

Close response

WebSocket Client Access Gateway WebSocket Server

 Section 2.6.2.1, “Scaling WebSocket,” on page 123

 Section 2.6.2.2, “Accessing WebSocket Resources,” on page 124
 Section 2.6.2.3, “Verifying a WebSocket Connection,” on page 124

2.6.2.1 Scaling WebSocket

When you deploy Access Gateway for a large scale WebSocket environment and the expected
concurrent users accessing the WebSocket application is more than normal, it is recommended to
tune Access Gateway to handle large scale requests.
To tune Access Gateway, edit the following files:
1. httpd-mpm.conf: Modify mpm_worker_module based on the number of expected concurrent
users. This tunes the number of threads of Access Gateway.

Setting Up a Basic Access Manager Configuration 123

 2. novell-apache2: To increase the number of open files for apache, increase the value of
ulimit. Use the command ulimit -n [new limit].
To set a temporary value, run the command using a terminal window. To set a permanent value,
make the changes in the /etc/init.d/novell-apache2 file.
For example, you can scale WebSocket connections up to 25000 connections by performing the
following steps:
1 In the httpd-mpm.conf file, make the following changes to mpm_worker_module:

<IfModule mpm_worker_module>
ThreadLimit 3000
StartServers 9
ServerLimit 10
MaxClients 30000
MinSpareThreads 9000
MaxSpareThreads 9000
ThreadsPerChild 3000
MaxRequestsPerChild 0
</IfModule>
2 In the /etc/init.d/novell-apache2 file, set the ulimit value to 8192 by using the
command ulimit -n 8192.
3 Restart Apache.

2.6.2.2 Accessing WebSocket Resources

Most of the modern browsers support the WebSocket protocol. You can access and verify the
connection by using the developer tools window.
Perform the following steps to access WebSocket resources:
1 Open a browser, then press F12 to launch Developer Tools.
2 Click Network > WS.
3 Open the link https://<published dns name>/<port> and specify the credentials.

2.6.2.3 Verifying a WebSocket Connection

You can verify if a WebSocket connection between a client and its resources is protected through
Access Gateway by verifying the following information in the Developer Tools.
Headers: Displays the initial WebSocket protocol upgrade and the 101 Switching protocols response.
Frames: After upgrading to the WebSocket protocol, Access Gateway establishes a WebSocket
connection. After establishing the connection, data transmission between a